
ADDRESS BOOK
Address and 'Phone Number Management for the Psion Series 3A
Shareware Program
(c) 1994 John W Dawson

V1.0, February 1994
1       Introduction

Address Book is an Application for the Psion Series 3A which you can use to 
manage addresses, 'phone numbers, and related information. It has a number of 
special features which make it more convenient and suitable for this purpose 
than the standard Database Application built into the Series 3A. These 
include: 

o       Alphabetic listing and searching of names;
o       Automatic formatting of addresses for printing envelopes;
o       Generation of RTF files for printing using a PC/Mac based Word 
        Processor; 
o       Enhanced DTMF dialling: 
o       Variable volume; 
o       Automatic prefixing of charge card account number and PIN 
o       Automatic prefixing of network service codes (for call diversion etc.);
o       Linking of records, to allow common information to be defined once 
        only but shared by more than entry. 

The Application manages one or more database of information about an 
individual or an organisation. Each entry in a database is a record which has 
fields to hold the following information: 

Full name;
Organisation (e.g. Company for which individual works);
Home 'phone number;
Work 'phone number;
Fax number;
Mobile 'phone number;
Electronic mail address;
Address;
Notes.

An entry may relate to a person, in which case the Name field will be present 
and optionally an Organisation. Alternatively the entry may relate to a 
Company or other organisation, in which case there will no Name, only an 
Organisation. 

There are four principle screens:
The Find  screen lists entries in alphabetical order, and allows alphabetic 
searches. 
The Show screen displays a single entry in full.
The Update screen allows existing entries to be modified.
The Add screen allows new entries to be added.

2       Getting Started

To install the Application carry out the following steps:

1       Copy the file ADDRESS.OPA into the \APP directory on the Internal 
        Drive or an SSD. 

2       Copy the files ADDRESS2.OPO and DIALOG.OPO into the \OPO directory on 
        the same drive. 

3       On the System screen use the "Install" (Psion-I) command to install 
        ADDRESS. The Address Book icon (depicting a book, 'phone, and 
        envelope) should now appear on the screen. 

4       You may find it convenient to assign a button to the Application, 
        using the "Assign Button" (Psion-A) command. 

You can now create an Address Book database by using the "New File" (Psion-N) 
command (while the highlight is beneath the Address Book icon). In the dialog 
box specify the name for the database and the drive where it is to be located. 
It is recommended that databases are stored on the Internal Drive or RAM SSDs, 
but not Flash SSDs. 

The Add screen (described fully below) should then be displayed, enabling you 
to start adding entries to the database. 

If you have an address database in a standard Series 3/3A format you can 
incorporate this into the address database using the "Merge Database" (Shift-
Psion-M) command (described fully later). If your database was created using 
the standard Series 3A template (i.e. including the fax label) then set the 
Database Type to Series 3A. Otherwise if the database was created using the 
Series 3 template (without fax label) set Database Type to Series 3). 

Once you have some entries in the database you can go to the Find screen by 
typing Escape or Diamond. 

3       General Points
Most of the basic features operate in the 'standard' way. Diamond/Shift-
Diamond switches to the next/previous screen. Menu displays the menus. 
Control-Menu controls the displaying of the Status Window. 

The Find and Show screens can both be zoomed, by typing Psion-Z or Shift-
Psion-Z. Also the Show screen is automatically zoomed to ensure all fields of 
an entry can be displayed on the screen. 

The "About Address Book" (Shift-Psion-A) command displays the introductory 
screen. You can exit cleanly from the Application by using the "Exit" (Psion-
X) command in any screen. 

4       The Find Screen
Entries are listed in alphabetical order. Entries for People are sorted by 
surname, which is generally taken to be the final space-separated 'word' in a 
name. E.g. John William Hedges and Peter Hetherington-Whyte would both be 
listed under H. 

You can override this, to cater for exceptions such as double-barrelled 
surnames without hyphens, e.g. Ralph Vaughan Williams which should be listed 
under V. You should enter such names with a double space between the last 
forename and the start of the surname (e.g. between Ralph and Vaughan). 

The  (double chevron eg '>>') character indicates the 'current' entry. 

Entries for Organisations are sorted by their complete names; e.g. Acme 
Software Company would be listed under A. 

You can find an entry by typing the initial letters of its surname (or 
complete name for an organisation). Use lower case letters only. As you type 
the program will progressively find the first entry which matches the letters 
entered, and display the entry with the matched letters highlighted. 

Upper and lower case characters are treated as equivalent. Accented characters 
are sorted and matched as the equivalent unaccented character; "" is treated 
as "a", "" as "o", and "" as "s". Punctuation characters are ignored when 
sorting and matching; e.g. O'Regan is listed between Oppenheimer and Oswald, 
and can be found by typing o r .... 

If you make a mistake when typing the sequence of initial letters then press 
the Escape key; this cancels the matching, and enables you to start the 
sequence again from the first letter. 

Once the entry you require is displayed on the screen you can select it 
immediately by typing the digit or shifted letter shown to the left of it. The 
entry is then shown in full on the Show screen. Enter or Diamond displays the 
current entry in full. 

You can move up and down the screen using the Up/Down arrow keys. Page Up/Down 
move a whole screenfull at a time. Home moves to the first entry, End to the 
last. Use of any of these keys cancels any matching in progress. 

5       The Show Screen
This displays the full details for a single entry. Only fields which have 
information in them are shown. Long lines are wrapped to ensure they appear in 
full, and the screen is automatically zoomed if necessary to ensure all lines 
are shown. 

Up/Down arrow keys move to the previous or next entry (if any). Home moves to 
the first entry, End to the last. 

6       The Update Screen
You can update the current entry by using the "Update" (Psion-U) command on 
the Find or Show screens, or by pressing Diamond on the Show screen. The 
Update screen is then displayed, showing all the fields for the entry and 
their current values if any. 

You can now change these values by typing text on the keyboard. If all or part 
of a field is highlighted then this is replaced by what you type; otherwise 
text is added at the cursor position. You can put a line break in the Address 
field by typing Shift-Enter; the cursor must be on the first line and the 
second line must be blank. 

Use the arrow keys to move around within a field or between fields. Use these 
keys with Shift down to highlight text. Home and End take you to the start and 
end of the current line. 

The Delete key removes the highlighted text, or the character to the left of 
the cursor if nothing is highlighted. You can cut and paste text between 
fields using Delete or "Copy" (Psion-C) with text highlighted and then 
"Insert" (Psion-I). 

If the contents of a field are too long to fit on the screen then they are 
scrolled automatically as you enter text or move around. 

The Enter key writes the modified entry back into the database. An entry will 
not be updated if both the Name and Organisation fields are blank. Use Escape 
to abandon the update, leaving the entry unchanged in the database. 

7       The Add Screen
You can add new entries to your database by using the "Add" (Psion-A) command 
or by pressing the Diamond key on the Update screen or Shift-Diamond on the 
Find screen. This takes you to the Add screen, whose operation is similar to 
the Update screen described above, except that all fields are initially blank. 

8       Finding Entries
The principle way of finding a particular entry is by alphabetical searching 
by name on the Find screen. However you can also make searches on other 
fields, using the "Find" (Psion-F) command. In the dialog you then specify the 
text you are looking for, which field to search (or all fields), whether the 
search should be case sensitive, and whether the entire field must match the 
specified text. 

The program will then tell you how many entries it found which match the 
specified criteria. If you ask it to display them then the matching entries 
only are listed on the Find screen. You can then navigate through these 
entries, display, update, print them etc. as normal. You can revert to 
displaying the entire database by typing Escape on the Find screen (or Escape 
twice if a name is highlighted). The program also reverts to displaying the 
entire database after the Add screen has been entered. 

9       Deleting Entries
An entry can be deleted using the "Delete" (Psion-D) command, or by typing the 
Delete key on the Find or Show screens. You are asked to confirm the deletion 
before the entry is removed from the database. 

10      Linking Entries
This facility allows more than one entry to share the same common information. 
The sort of situation where this might be useful is where you have a couple 
who have the same address and home 'phone numbers, but different work 'phone 
numbers. Each individual can have their own separate entry, but the common 
address and home 'phone is only defined in one entry; the other entry refers 
to this 'parent' entry. If the couple should move then you only need to change 
the address in one place. 

Another way of using linking is to set up a 'parent' entry for a Company, and 
have several linked entries for individuals in the Company. 

You can create a new entry linked to an existing 'parent' entry using the "Add 
Linked Entry" (Psion-L) command. The 'parent' entry must be the current entry 
on the Find or Show screen. The Add screen will then be displayed, with the 
field contents derived from the 'parent' shown in grey. These values cannot be 
modified, but can be replaced by typing new contents. 

You can link an existing entry to an existing 'parent' using the "Link" 
(Shift-Psion-L) command. First select the entry to be linked on the Find or 
Show screen and type Shift-Psion-L. Then select the required parent and type 
Shift-Psion-L again. 

An entry can only be linked to a single 'parent', but a 'parent' entry can 
have any number of other entries linked to it. 

When a linked entry is displayed on the Show  screen then for any of its 
fields which are blank the contents of the field in the 'parent' entry are 
shown instead. You can suppress the showing of field contents derived from the 
'parent' by entering a single space in the field. 

When you update a linked entry fields derived from the 'parent' are shown in 
grey and cannot be changed, only replaced. 

You can remove a link from an entry with the "Remove Link" (Shift-Psion-U) 
command. You are asked to confirm the removal. 

11      Importing Data
If you have existing Data files containing address information then you can 
import this into an Address Book database. If the Data files conform to the 
standard template supplied with the Series 3 or Series 3A then you can use the 
"Merge Database" (Shift-Psion-M) command to do this directly. As well as 
specifying the name and drive for the file to be imported you must specify 
these characteristics of the imported file: 

o   The Database Type - whether it conforms to the Series 3 layout, or to the 
    Series 3A layout which has an extra Fax label; 

o   The Name Structure - determines how the Name field is interpreted: as a 
    person's name with the Surname First or Last, or as the name of an 
    Organisation. 

Note, if the merged data file actually contains a mixture of entries for people 
and organisations, you can merge it using the surname first or last options, 
then use the "Make Organisation" (Psion-O) command to convert the entries 
which are actually for organisations. This command moves the Name field to the 
Organisation field. 

If you have data in a file that does not conform to one of the standard 
templates then it is very easy to write a simple OPL program to convert your 
file to the format of an Address Book database file. The structure of an 
Address Book record is as follows: 

Index%
Link%
Surname$
Forenm$
Organ$
Home$
Work$
Fax$
Mobile$
Email$
Addr1$
Addr2$
Notes$

Index% and Link% are numeric fields used internally by the program. Index% 
should be set to a value unique for each entry and greater than 1, taking the 
value of POS + 1 for each record would be suitable. Link% should be set to 0 
for each entry, unless you want to create linked entries, in which case it 
should be set to the value of Index% for the 'parent' entry. The other fields 
are all strings whose meanings should be obvious from their names. 

Once you have created a file with the above record structure you can open it 
directly with the Address Book Application. Alternatively you can merge it 
into an existing Address Book file (see below). 

You can also merge the contents of another Address Book file into the current 
database, using the "Merge Addresses" (Psion-M) command. Note that in this 
case the program makes two passes through the input file, in order to 
correctly maintain link information. 

Note that although Address Book file are OPL Databases, they cannot be created 
or viewed using the built-in Database Application, since they contain non-
string fields. 

12      DTMF Dialling
You can dial the current entry on the Find or Show screen by typing Dial 
(Psion-Help). This displays the Dialling screen which lists all the telephone 
numbers for that entry. Select the number you wish to dial using the Up and 
Down keys. 

The Tab key dials the number exactly as shown. Enter prefixes the "dial out" 
code, e.g. to make an outside call via a switchboard. Type c to automatically 
prefix the account number and PIN for a BT charge card call (or similar). Type 
d to dial the number with the code and terminator for a special service (such 
as BT Star Services Call Diversion). Type Escape to quit from the Dial screen. 

After any of these buttons are pressed there is a short delay; this allows you 
to position the loudspeaker correctly for successful dialling. You can dial 
further digits by pressing any of the 0 to 9 and *, # keys while the Dial 
screen is displayed. 

If a 'phone number entry contains non-diallable characters, then only the 
digits preceding the first such character will be dialled. E.g. if an entry 
contains: "0123 456789 x321" then only 0123 456789 will actually be dialled. 

This version of the program does not support international dialling. However 
numbers should be dialled correctly when making calls within the same country, 
even where the numbers have been entered in standard Psion international 
format, so long as any national prefix is included  (e.g. 1 321 4567890 
[USA]). 

Note the c and  d buttons will not be displayed or activated until you have 
set up an account number and PIN or service code; use the "Dialling Setup" 
(Shift-Psion-D) command to display the Dialling Setup Dialog. When setting up 
the Divert Code specify both the code prefix and the terminator, separated by 
a space. E.g. for Star Services "Divert on No Reply" you should set *61* #. 

You can also set the code required to obtain an outside line. E.g. if you have 
to dial 9 and then wait for a second dial tone you should set 9,. 

The other fields allow you to specify the duration of the tones, the pause 
between tones, and the length of a delay; units are 1/32s of a second. You can 
also set the volume of the tones; allowed values are 0 to 5, with 5 the 
quietest. (5 seems to give the most reliable results with most 'phones.) 

13      Printing
The program is designed to print by outputting directly to a host computer 
(IBM PC or Apple Macintosh) via the Serial Link. It can produce files either 
in Rich Text Format (RTF) or in plain text format. RTF files can be printed 
using a compatible word processing program, such as Microsoft Word. They 
contain all necessary formatting information, and should not require further 
formatting. Text files can either be sent directly to a printer, or imported 
into any word processing program for formatting and printing. 

To start printing use the "Print" (Psion-P) command (after first establishing 
the serial connection). In the dialog you can then specify the Destination 
disk and directory path where the print file will be created, as well as the 
Format (RTF or Text). The file will be given the same name as your database 
file, but with extension .RTF or .TXT. 

You can choose from two Layouts: 

o       Listing - for listing the full details of entries. This prints all 
        fields in an entry, with the corresponding labels. 

o       Envelopes - for printing addresses directly onto envelopes. This 
        prints the Name and/or Organisation, followed by the contents of the 
        two Address lines. Each element in the Address which is separated by a 
        comma is printed on a separate line, except that house numbers are 
        printed on the same line as the following street name, even if 
        separated by a comma. 

Print Organisation is only relevant when printing envelopes, and controls 
whether the Organisation is printed in addition to the Name. If you select 
Prompt then for each entry which has both a Name and Organisation you will be 
asked if you want the Organisation printed. For entries which have no Name the 
Organisation is always printed. 

Entries controls which entries are printed. You can choose to print All 
entries in the database, or selected Individual entries. Additionally if you 
have used the "Find" command to select a subset of entries, then you can also 
choose to print these Selected entries. 

If you specified All or Selected  entries, then these are printed immediately 
you terminate the dialog with Return. Once this is complete (the "Printing" 
message is no longer flashing) you can break the serial connection, and print 
the file on the host. 

If you specified Individual entries then you must select each entry you want 
printed, by using the "Print Entry" (Psion-P) command. When all required 
entries have been printed you terminate printing with the "Finish Printing" 
(Shift-Psion-P) command; only then can you break the serial connection and 
print on the host. 

Note for Macintosh users: you should set the Host to Mac in the Print Dialog. 
This gets round some of the problems associated with transferring RTF files to 
the Mac, in particular the handling of characters with codes greater than 127 
(e.g. accented characters), which are different in the PC and Mac character 
sets. In theory this should be catered for by the RTF format, where such 
characters are represented by hexadecimal number strings. The RTF file also 
includes an indication of the "origin" of the file (e.g. PC or Mac). Hence the 
translator reading the file should be able to convert these characters to the 
equivalent characters in the destination machine's character set. 

In practice I have found the word processor I use (Microsoft Word V4.0 for 
Macintosh) does not handle this completely; it converts the first few 
characters correctly, but then gives up! This may be a reflection of the fact 
that there is no "standard" PC character set. 

The solution I have adopted is to output such characters as the actual 
characters themselves, and then rely on the conversion built into the MCLINK 
program to convert them to the Mac character set. This requires that "*.RTF" 
is added to the list of file extensions in the MCLINK.EXT file. If Host is set 
to Mac then the RTF file is generated with "Origin" set to "Mac", i.e. the RTF 
translator on the Mac is fooled into thinking the file was generated on a Mac 
and will not attempt any conversion of characters. 

You can change the layout and appearance for printing both Lists  and 
Envelopes individually, using the "Print Setup" (Psion-Y) command, which 
displays the Print Setup Dialog. If you want to change values in any line of 
this dialog you must use the Tab key. Use the Up and Down keys to move between 
lines. 

On the Page line you can specify the Width and Height of the paper (in 
inches), and also the Orientation (portrait or landscape). Note the Word 
Processor I use (Microsoft Word for Macintosh V4.0) does not appear to take 
notice of paper orientation commands in RTF files. Therefore it may be 
necessary to set this manually from within your Word Processor before 
printing. 

On the Margins line you can specify the sizes of the Top, Left, Bottom, and 
Right margins (in inches). For List output you can also specify the Tab 
position, where field values will be printed to the right of their 
corresponding labels. 

On the Font line you can specify the Name, Family, and Size (in points) for 
the font. You can use any combination that your Word Processing program will 
recognise. For Envelopes you can also specify printing in Bold and/or Italic. 

The Enter key ends the dialog and applies the changes. Use Escape to abandon 
the changes. 

14      Problems and Troubleshooting
At time of writing this I am not aware of any outstanding bugs in the program. 
However it has not been rigorously tested to the same standards as commercial 
software. Also it is a very complex program which does rather a lot of dynamic 
memory allocation and PEEKing and POKEing. Hence there is considerable scope 
for cocking things up! I cannot therefore be held responsible for any 
consequences of using this program. 

The most likely problems to be encountered are associated with running out of 
memory. This is most likely when attempting to display a new screen or dialog. 
The program is designed to trap such occurrences and either abandon what it 
was trying to do or exit gracefully. 

If the program should exit in an uncontrolled way, or has to killed off 
(because it appears to be locked up), then when it restarts it will have to 
rebuild its internal index tables. This can take a few minutes, but it does 
indicate its progress. 

If the program should start behaving erratically (e.g. listing entries in 
wrong order or missing out some entries) this may indicate corruption of its 
internal index tables. It may be possible to deal with this by exiting 
normally and deleting the index file it creates (this has same name as the 
main database file, but with .IDX extension. Then when the program restarts it 
will rebuild its tables, hopefully correctly! 

If you have queries or comments about this program I can be contacted at 

19, St Edward's Rd.
Reading
Berkshire
England
Telephone: +44 734 666185
Please call outside working hours if possible!

15      Registration
I am making this program available as Shareware. There is no registration 
procedure; the software as distributed is fully operational. However if you 
find this program useful then I would ask you to send a donation (suggested 
10.00 UK pounds Sterling) to a charity I am closely involved with. Reading 
Steiner School Project (Registered Charity No. 297857) is developing education 
in the Reading area based on the work of the Austrian educationalist and 
philosopher Rudolf Steiner. 

Please make cheques etc. payable to R.S.S.P., and send them to 

Department ADBK 
Alder Bridge School 
Mill Lane 
Padworth 
Reading 
RG7 4JU 

Please do not send any technical queries etc. to the School! 

Please do distribute this program freely, providing you do not make any charge 
(other than to cover reasonable costs of distribution) and you include these 
notes. 

16      Future Developments
I have developed this program for my own use, so its facilities and operation 
very much reflect my own requirements. However there are a number of obvious 
ways it could be extended and developed, to make it more useful to a wider 
range of people. These include: 

o       Making the record structure and labels user configurable;
o       Dialling of international calls, perhaps through interface to World;
o       Direct output to printer, using resident drivers;
o       A 'cut down' version for the Series 3.

I would be very happy to hear from anyone who would like to collaborate on any 
of these, or who has any other good ideas for developments. 


