sibo-playground/docs/1-03 Series 3 3a Programming Guide 2.30_djvu.txt

SIBO 'C' Software Development Kit 


SERIES 3/3A PROGRAMMING GUIDE 


Version 2.30 


March 1, 1999 


(C) Copyright Psion PLC 1990-98 


All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC, 
London, England. Reproduction in whole or in part, including utilization in machines capable of 
reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse 
engineering is also prohibited. 


The information in this document is subject to change without notice. 


Psion and the Psion logo are registered trademarks, and Psion, Psion MC, Psion HC, Psion Series 3, Psion 
Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of Psion PLC. 


TopSpeed is a registered trademark of Clarion Software Corporation. IBM, IBM XT and IBM AT are 
registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered 
trademarks of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer 
Inc. VAX and VMS are registered trademarks of Digital Equipment Corporation. Brief is a registered 
trademark of Underware Inc. Psion PLC acknowledges that some other names referred to are registered 
trademarks. 


Contents 


1 Series 3 Programming Overview.............ssccsscssscssscssccssccsscsecssscseesssssssscccesssscssesssscsessseseees 1-1 
Programming possibilities ..............cceseccceeseseceeeseceeseceecceeaceeceseaeeeceeeeeseeeeeeeseeeeeeenaeeeeanees 1-1 
Differences between .app files and .img files... eeeceeeesecceeeeeeeeeneeeeeesaeeeeeeeneeecnneeeenees 1-2 

Addsfile: Sts sic sst3sctisscssiastosend lees sues thssapteteaioteasdesdodstanecae audeusoastealateasde aeedcauteaiaseandae 1-2 
Pre-defined add-file Slots:.:.iociictsih ici ek hens iaeieleitii ond ubetie choca haces 1-2 
Running programs via RUNIMG S3....... cee eeseeesseeseseceseecesceceseeeesaeecsaeecseessaeessneeees 1-3 
Program files with and without icon files 0.0... eeeeeseessseeseneecsneeseeecsaeeeseeesneeeesaes 1-3 
Resource files and shell data files... ee eesecsseecsseeceseessceceseceesaeecsaeesseeseessseeeesaes 1-3 
Customised add=fless.. -iou..:. aca tecteeiiied iis Rachie ehdila se beuhod shan buaadeedesioegsitasdetaseeade 1-3 
Finding add-files within a .app file... cece eeeeesseeceseeeesseeseeeesaeecsaeesseeeesaeneeeeesaes 1-3 
Multi-lingual applications ..............ccceeeccceeseecceeeseeeeeeeeeeeeeeeceseaeeceeseneeceneeeeeeeaeeeeeenneeeeneae 1-4 
Environment variables on the Series 3 .........eeseeeeesseeesseecsneecsececeecsseesesaeeesaeecsaeesseeeaeers 1-4 
AVOIC S$ :SIQTS) 05. .:252.ch caveats Seccaces tees cbutducasoecee Sues ned Seanetescusssuayeodbobertea hs cadaed sandestoeneect ta 1-5 
Series. 3 family compatibility. s:2.::).cissssdscvei sks snndesidvaviesesats.oriesb Aaatesidhapdevinisdspbianser ieee dos 1-5 
Series 3/Series 3a/Workabout compatibility ......... ec eeeeeeseeesseecneeceseeeeseeessaeeeseeseers 1-5 
Compatibility with Series 3c and Siena... eee eeeeseecsseeeseeeseecaeesseessseeeesaeeesaeeaes 1-5 
Programs written for the Series 3.0... eeceeseesseecsseeessceceseeeeseceseeessaeecsaeecsaeeessereeeeees 1-5 
Programs written for the Series 3a .......eeceeeeeeseecsseessseeceseeeeseeeseeeesaeecsaeecseeseneeeeeeee 1-5 

2 Communicating with the System Screen ..............ccccscsccssscssssssecsscssecssssecsssccessssceessssssesseesors 2-1 
INtrOdUCH OMe s<ie2.1i2ii thas cbids hanicasdiatige Mateo tia aa aosds cae Mosta ts Mreatieiohits ea tines heey 2-1 
Creating: Shed files) vescssctteehe cai ssc Sih douse eh bach eguie tei bae eh gvag eh eegoaede eags be shonededte tod asuenees 2-1 

‘TPhé:format: of..ms files ...3:5:t.ccisss stiosst etd Asche Aasidoa Bashers 2-1 
Default extension 35:55: aus cabsavesssigh fore thessits Bag passteors Us higeatiteest ods Ry eietews Taba teeercts 2-2 
Pub e Name sets serie vicassgaliacetiankesyagansoes iaauesuaeestvoeetasea rasbea obabasensasecasieaesgeananyicasieeasacates 2-2 
Default director ys. ci seeeci Sats ccseock ccessushodeseaeh oceeeentosontent nageancessenuses sagnancnedendncnnneransseneess 2-2 
Application type nUMDEe®rs ...........cccsccceeseseceessceceesececeeseneeecesnneeeceeeeeeeseaeeeessnaseeeeenees 2-2 
Multi-lingual forms of .ms files... ees eeseeeeseeceseeeseecseessceeesaeeesaeecsaeesseessneeeesaes 2-3 
Pure file list applications.............ccccccceeseescecesseceeeeeeeeceenneeecsseeeceesaeeeseseeeeeseeeeeseeenees 2-4 
Aliasing applications ............cccccceesssccceesseceeeeescecceseneeeceeneeeeeseaeeecseaeeecseaeeeeeseatesesenneeeeeeeeas 2-4 
Creating-als fless.c.5:8 liu td css sist nites ietait Asada Masse ssnaiieas 2-5 
Active aliasing and passive aliaSINg.........ceeececeseecsseecsseeceseeeesseecsseeseseeeesaeessaeessaeeeees 2-5 
Active aliasing in the built-in text editor... eee eeeeeesneecsneeeceseeeeseeeesaeessaeeseneeesee 2-5 
How aliasing, Works: ic-cbistiincnisi ea din eee wet aed oh ah owen es evans 2-6 
Epoc reserved: statics: oss cdgeiasicedetsascvetiys hecvssuseesaeies hvaou she cuss vasnssae ovedadaesuscesssvutsdes seanesassones 2-7 
DatProcessNamePtr:(OX22):5 2.05 2-b accents eibhel ceeeestaie ova ilanaiandnanatitis 2-7 
More on the file lists in the System Screen ........eseeeeeseeeesseeeeseecseeecsececesaeecseeseeeeees 2-7 
Assigning application buttons ........ eee eeeeescecssceeeseeeesseecsacecseecesaeeesaeecsaeesseeesteeeesaes 2-8 
DatUsedPathNamePtr (OX3¢) ........cc:ccccccccssssssseeeeececeessesneeeeeeeceessesseeeeeeeseeeesseeeeseesenes 2-8 
DatStatusNamePtt (OX36) is :2.08 8 Aas titiest Bai dds Aad as 2-9 
Datleocked (Ox3ai).2c sctag estes isesagasiceatceengesseneecaiessuesaeg saree eea teak GO 2-9 
The'Series 3 command limes o.2.5.4. fics sist iefeesecrsiben oad eee ahiesbiedeas ous evudeeb ns ebehlelaeens 2-9 
Summary of command line format... eee eeeeeesecsneecsseeeeseeeesaeecsaeesseessseeeesaeeesaeers 2-10 
Supplying a command line from the SIBO Debugget .......... eee eeeeeeseeeeseeeeneeeeneeeeenes 2-10 
From command line to reserved Statics .........:eeeeeeseceseecssceceseeeesseecseesseeeeseeeesaeeees 2-11 
Applications that disregard their command line.................cceeecseeeeeeeeeeeeeeeeeeeeeneeeeeeeee 2-11 
Creating directories When required ............eeseeeseecseseeeseecseeceeecsseeeesaeeesaeersaeesseeeees 2-12 
Messages from the System Screen ..........eeeesceesseeessceeesseecseecsseecsseeeesseecsaeesseecsseeeesaeeesaeers 2-12 
Shutdowm Messages...2.5Ace.hiiiscosdsuseascsesssangl casi ceaazensdaaicnasiguapesineieaiedeatanasuoeieaaees 2-12 
Switchfiles MeESSAsesicc.ii.8:ceiseahssch sit hols ncdac chs HeasseoceuSeech bach leshoestocgh Guahtesteasboessaoenedi seuss 2-12 
How messages from the System Screen are received... ees eeseeeeseeceseeeeteeeseeseeeeeee 2-12 
Contents of the new command line for System Screen messages ............ssceeeseeeeeeeeeee 2-13 
Other possible types Of MeSSages..........:-eseesseeceseeceseeeseecseesseecsteesesaeeesaeessaeesseeeees 2-13 


Multi-lingual aliasing of Word. app...........ceseceeeseesseeseseeceseceeesseecsaeecseeeeesaeessaeeseeeesns 2-13 


GENERAL PROGRAMMING MANUAL 


ii 


3 Enhanced Sound Output. ...............csccccssssccssscssecsscssecssscseesssscsesssscssesssscsesssssssesssscsssssssssssesssoees 3-1 
Trt Od uC tris ae need echoes eed ak antes eal ads est ong ek aad wstone saat dvb tp naet ae daees eek Seta eet eee 3-1 
Sound on the Series 3.s...2:..ccyohivseaesi yeisigieae eayhelnisiyanel Wiener elton spank 3-1 

TMtLOUUCHONY! st .etshe on oto enctnd dn ahead aot Rite et a ie ae Aisi Rute aht wt ae 3-1 
The sndfrce and snddvr device drivers ...........ceeceeseecsscecssceeeseeessseecscecsseesesaeeesaeeesneers 3-1 
Tristalling Sin ited sos se ces ceases: ceessad este edat ves otes ene ventewep ones sche otntavey tes anhersatenuseceteete 3-1 
Opening a channel to MUS? ..0......eeceecsenecseessecenesscesnnetoncsepscecesonesenesnonsenssenesesenenees 3-2 
Actilally Creatit S SOUS oo. 52s. oe. vatnd ccovved ahs etunechvoued axhectndscbvoues ste eshn toch sonst acnestuleslvanstsaee 3-2 
BxXampletsieavsscut ksh avai inn asthe a ia ada a ade neve 3-3 
Possible tonesis s,s ss: fisee faces iat ses wep oveptanpavec eves obisiaetaiiy etet edupiget vegestedesaget otis etsbedevonet 3-3 
PAaliS@Si sivas esol ainag Bester ues vine hes vesanhes ven e ea bieayh nigaehs Meaapd ania Seti Synn yee 3-3 
When to open and close MUS:........eeeeeesecesseeesseecesceeesseecsacecsscecesaeeesaeessaeesseeeeneeeesaes 3-3 
When to install and de-install the Idd file... eee eeseecesneeesneeesneeeseeesseeeesaeessaeers 3-4 
Sound On tHe: SEries Bais 25 elce cca deset ilu eden ceed set oisdeceseder stotleutyesctevlevaceterteesstedese det svigeautetetoeets 3-4 

A: WSE-OF SPY: APP scecsscssrascssescacsssessascsGonsacsseasoaseosesdissosvsasceosesssesdusessssoseasseseessosssbenssesveassesevbasosseses 4-1 

Tint OA CHOU s55 52. ss ec .2h. Pore tego s ees dike duis Fades ous teens da Babe cou Tevactee Bebe sik ceeseeds thoes enewisde de sna eae ied 4-1 
Buildiiig Spy. apprsiasiseissecasioveteaescetealsaceldawsscateaciaeaieangcatsacsaeatagextaguesensdemeensagieoansenses 4-1 
The main display ...........ccececccccsssscccesencecceeseeecessaceceesnaeeeceeaeeeceneaeecesenaeeecseeeeesenaeeeesenneeeeneas 4-1 
Heap :StatistiCs sc) scsisscavsitcvaeseccaadaceesansces dave seucsessseuscvssdedecssuscuscusasauesessiassusatiaccvantess 4-2 
Stack: Statist Cs ‘ssscvss sein cevyecudssivenut docks cove hveies Saves rats ckbedeh oluke ealactosdeh stehe setheosteh sunhs seen 4-2 
SESMENE StALISLICS s2isc8,22sidsestesiacessdasanenbactsceadasapestas agent aestenbectacsondateen tes laouendateestgiias 4-2 
Tests for heap integrity ...........cececscceesssceceesseeceeseeecceseaeeeceseneeecseaeeeeeseeeeeesneeeeeenees 4-2 
PLOCESS PLIOTILIOS sf. 55s. fete divs fees oes tddacissdaadeaideded rad cacdeaccudsdisateiacdvsunees susacaascvicieesesaneas 4-2 
Othier dattaresc: cccs2-0b tac ectets Abed oeeseeteteeleb tease ela ckeieds ess dade deevsivers iad oesieren Hues 4-3 
Logging Window Server statistics ..........::cesceesscecsseeeeeeecscecseeeeseeeesseecsaeersneessteeeesaes 4-3 

Appendix A Technical Specifications ................cccsccccsscsscsscsseccsscscecsscccessssccesssscssssssccsessssesseees A-1 
Psion Series 3a Technical Specification .............sceescccsssceecsseecssceceseeeesaeeesaeecsaeesseeeeseeeesaes A-1 
Psion Series 3/38 specification ...........cceeccesseeesseecsseecsscecsseecesaeecsaeecsaeecseessneecesaeessaeeesaeers A-2 
Psion Series 3c Technical Specification 0.0.0... .eseeseccsseceecsseecsseeceseeeesaeeesaeecseessseeeeseeeesaes A-3 
Psion Siena Technical Specification...........cscsescccsseecsseceecsseecssceceseecesaeeesaeecsaeessseeseseeeenaes A-4 
Psion Siena SSD Drive Technical Specification ...........ceceeeseseseeceseeceeseessseeceseeeesaeeesaeees A-5 
Psion Serial 3Link Technical Specification ............eeeeessessseecssceessceceeseecsseecsseeeesaeeesaeers A-5 

PC Serial 3Link to Apple Macintosh converter ............c:cessceesseessseeceseeeesseeseaeessseeeeee A-7 
PC Serial 3Link to Apple Macintosh converter .............s:cessceesseecsneeeeseeeesseeesneeseeeeees A-7 
Modem Adaptor cable..........eccccceessccccessceeeeseneeeeeseneeecesneeeeeseaeeeesseaeeeeseneeeeceeeeeeeseeeeess A-7 
Serial Printer cable (Series 3a) - Technical Specification ...............cceeccceeesseeceeesneeceeeeennees A-7 
Serial Printer cable (Series 3c/Siena) - Technical Specification ............:::cccssscceeesseeeeeeeeees A-8 
Psion PC Link cable Technical Specification ...........eeceeeeseecsseeceseeesseeeeseesseessneeseseeeenaes A-8 
Modem Adaptor Cables. e....ccssuecevietesstegesetsteg teh seep vies sat etstcawpsdet ovng aut levgotes ovtg oakteee sbeee} A-8 
Psion Mac link cable Technical Specification ............ cc eeeeeeseecsseeeeseeceeseeceeecsseeeesaeeesneers A-8 
Psion 9-to-25 way D-type adapters Technical Specification...........ceseeesessseeceseeeesneeeeneers A-9 
Modem 9-to-25 way D-type adapter - wiring diagram ......... eee eee eeseeeeseeceneeeeseeeeseeeesneers A-9 
PC (XT) 9-to-25 way D-type adapter - wiring diagram ........... ce eeeeeseeeseeceneeeeeeeeesneeesneers A-9 
Printer 9-to-25 way D-type adapter - wiring diagram .......... eee eeeeesneeeeseeceneeeeseeeesaeeeeneees A-10 
Psion Parallel 3Link Technical Specification ........... ce sceesecceseeceseeeseecsaeecseecsseeeesaeeesaeers A-10 
Psion Parallel Printer Link Cable Technical Specification... ceeseeesceseseeceseeeeeeesneers A-10 
Psion PC Card Modem Adapter Technical Specification ...........ecceeseeeseecsseeeeseeeesneeeeneees A-11 
Psion Travel Modem Technical Specification ............ceesesesecssceceseeeeeseeesaeecseeesseeeeseneers A-13 
Psion 3Fax Modem Technical Specification ...........ceseeeceesseecsseecsseecssceceseeeesaeecsaeesseeeeee A-14 
Appendix B Differences Between Psion Series 3 Models ..............csssssccsscssecsscsseccsscsceessssseeeees B-1 
Current models in the Series 3 family... eee eeseeeseeceseeceseeecsseecsaeecseecesaeeesaeecsaeessaeeeees B-2 
Superceded models in the Series 3 family ....... cee eee eeeseceseeceseeceseeeesaeeesseecsaeesseeseseeeenaes B-3 


CHAPTER 1 


SERIES 3 PROGRAMMING OVERVIEW 


Throughout the Series 3 Programming Guide, reference to the Series 3 machine should be taken to 
include the Series 3a and the Workabout unless stated otherwise. See also the Workabout Programming 
Guide for further information specific to that machine. 


Programming possibilities 

In general terms, there are six different levels at which programs can be written for the Series 3: 
e using OPL, creating .opo or .opa program files 
e using CLIB, with user interface restricted to console i/o of the getchar and puts variety 
e using PLIB, again with user interface restricted to console i/o 
e using WLIB, accessing the graphics and windowing capabilities of the Window Server 
e using Hwif, with its support for menus and dialogs similar to those available in OPL/w 


e using HWIM, FORM, OLIB and (for the Series 3a) XADD, the object-oriented DYLs built into 
the ROM. 


All but the first of these uses the C programming language. 


For programming in OPL see the Series 3, Series 3a and Workabout Programming manuals, or the SIBO 
OPL Software Development Kit. 


For more detailed information about PLIB library routines and the window server see the PLIB Reference 
and Window Server Reference manuals respectively. 


Programming using Hwif is also covered in its own separate manual, Programming in Hwif. This manual 
is particularly recommended on account of its relevance to the Series 3. 


For details of object-oriented programming see the object oriented sections of the C SDK, starting with the 
Object Oriented Programming Guide. 


The present manual focuses on features of the Series 3 and Series 3a that are by-and-large unique to these 
particular computers (as opposed to other computers in the SIBO range, that is, the HC and MC 
computers). These features include: 


e the difference between .app and .img forms of program file 

¢ communications between applications and the System Screen 

e the specialised form of the command line for applications 

e some device drivers unique to the Series 3 and/or Series 3a 

e development tools particularly suited to the Series 3 and Series 3a computers. 


e writing applications that run on all machines. 


SERIES 3/3A PROGRAMMING GUIDE 


Other parts of the SDK that may be found of particular relevance to programming for the Series 3 
include: 


e the descriptions of file formats used by various applications, in the Additional System 
Information manual 


e adescription of the special form of printer driver files used on the Series 3, also in the Additional 
System Information manual. 


Before proceeding further with this chapter, the reader is recommended to be familiar with the basic 
contents of the General Programming manual. 


Differences between .app files and .img files 


Strictly speaking, there is no real difference between files with extension .img and those with extension 
.app. For example, although the System Screen usually expects to install .app files, it will also, if 
requested, install suitable .img files. 


However, by convention a .app file contains one or more extra so-called add-files embedded within it, in 
addition to the core .img file itself. These files may include: 


e a.pic file providing the icon for the application 
e a.rsc or .rzc file providing the resource file for the application 
e a.shd file providing the shell data for the application. 


Any such add-files can be added into the .img file automatically, via the operation of emake.exe, at the 
time the .img file is itself created. What controls the set of add-files used (if any) is the presence or 
absence of a suitably named add-file list (.afl) file. 


Add-file lists 


An add-file list (afl) file is a text file containing from one to four filenames. For example, the contents of 
a file tele.afl could be: 


tele.pic 
tele.rsc 
tele.shd 


When any .pr project file is invoked that leads to the building of tele.img, the existence of a file tele.afl is 
checked for. If such a file is found, the files listed therein are combined with the core .img file to form a 

larger .img file as output. By convention, .img files that contain embedded add-files are renamed to .app 
files. 


See the chapter Building an Application in the General Programming manual, for more details. 


Pre-defined add-file slots 


The RscriILe class in the OLIB library can find resource files embedded in a .app file, but only if they are 
placed in the second of the four slots. 


The System Screen expects to find a .shd file in the third add-file slot of a program being installed, and 
indeed will refuse to install it if no such data is found there. 


The Window Server, however, will find a .pic file (or a .fon file) at any of the four add-file positions 
within a .app. In view of the requirements for resource files to occupy the second slot, and for .shd files to 
occupy the third slot, .pic icon files are usually placed in the first add-file slot - as in the above example. 


At the time of writing, there is no mechanism to specify a file for (say) the third add-file slot, while 
omitting the second add-file altogether. For this reason, it may occasionally be necessary to create and 
maintain a zero-length file for the second slot. 


1 SERIES 3 PROGRAMMING OVERVIEW 


Running programs via Runimg 


An alternative to installing a program in the System Screen with its own file list is to run it from the 
RunImg icon: 


e the user presses TAB while the highlight is within the RunImg file list 
e the user navigates the file selector until it selects the program file 
e the user presses ENTER to start this program. 


This procedure can be simplified if the program is placed in a top-level \img\ directory, and given the 
extension .img. In this case, the program will automatically appear as an entry in the RunImg file list. 


However, a program run in this way will receive no special command line from the System Screen. Nor 
will it receive any Shutdown or Switchfile messages from the System Screen. (These messages are 
discussed in the following chapter). 


Program files with and without icon files 


An application can simply not have an icon, although in this case the system screen will simply refuse to 
install it. The application can, however, still be run from RunImg, in which case, an empty icon boundary 
will be displayed in any status window used. 


Icon files, such as tele.pic, may be produced by a variety of means: 


¢ using the Jconed demo application that can be built using the Hwif part of the SDK or, for the 
Series 3a and Workabout, the Iconeda application that is installed in a \sibosdk\s3atool directory 


e using the Window Server tool wspcx.exe on the .pcx output of a PC program such as Windows 
PaintBrush. 


The .pic file can contain: 
@ a 24x24 bitmap for a Series 3 icon. 


¢ two 48x48 bitmaps for a Series 3a icon - the first and second bitmaps specify the black and grey 
planes respectively. 


@ a 24x24 bitmap for a Series 3 icon followed by two 48x48 bitmaps for a Series 3a icon. 
The format of .pic files is given in the Bitmaps section in the Window Server Reference manual. 


Resource files and shell data files 


See the Resource Files chapter of the Additional System Information manual for a description of the 
format and uses of resource files. 


Shell data files are discussed in the following chapter. 
Customised add-files 
In most cases, at least one add-file slot will be free for use by the application itself. 


One important reason to build an extra file into the .app file, rather than leaving such a file separate, is 
that it diminishes the chance of a user copying the .app file from one SSD to another but neglecting to 
copy a vital associated file at the same time. 


Finding add-files within a .app file 


Ordinarily, applications have no need to find add-files within themselves, since system code takes care of 
this on their behalf. 


One possible exception is when an application needs to access a customised add-file. In this case, 
knowledge of the format of the header of a .img (or a .app) file is required. In fact, this header just 
contains the same information as is returned by invoking edump.exe. 


The header of a .img file is described by the ImgHeader struct, defined in epoc.h. See the chapter 
Processes and Inter-process Messaging in the Plib Reference manual for a discussion on this struct. 


SERIES 3/3A PROGRAMMING GUIDE 


An example of code that attempts to locate a resource file in the second add-file slot of a .app file is as 
follows: 


GLDEF INT rscfile_rs_init (PR_RSCFILE *self, TEXT *name) 


{ 
ImgHeader head; 


/* self->rscfile.offset is zero by default */ 
f_open (&self->rscfile.pcb, name, P_FRANDOM|P_FSTREAM|P_FSHARE) ; 
if (p_read(self->rscfile.pcb, &éhead, sizeof (head) )==sizeof (head) ) 
{ 
if (!p_scmp (&head.Signature[0],"ImageFileType**") ) 
{ /* we have a .img file */ 
if (!(self->rscfile.offset=head.Add[1].offset) ) 
p_leave (E_FILE_INVALID) ; 


Multi-lingual applications 


The topic of multi-lingual applications is discussed in general terms in the course of the Resource Files 
chapter of the Additional System Information manual. 


There are some issues about the set of possible command hot-keys ("menu accelerators"), however, that 
are particular to the Series 3. 


The set of possible accelerators varies from language to language on account of the keyboard changing. 
All languages must, however, support the 26 accelerators 'a' through 'z', together with four more. 


These additional accelerators are '+', '-', '*', and '/' in most languages. The only exceptions so far are 
French and Spanish (and Belgian, which uses the French keyboard): 


e French replaces '/' with '?' 


e Spanish replaces '*' with '>' and '/ with 'i'. 


Applications which fail to take account of these changes when they are translated into another language 
will find they end up carrying a "Iame" accelerator: the accelerator is displayed on the menu, but there is 
no way for the user to press the required key combination. 


Environment variables on the Series 3 


Environment variables can be a powerful programming resource whilst being, at the same time, 
potentially anti-social. 


There are two aspects to this: 


¢ environment variables consume space in a special RAM segment devoted to them - the more 
environment variables are created (and the larger these are), the greater the chance becomes of 
other applications failing to work properly - on account of not being able to create their 
environment variables. 


e name clashes are possible - data stored in an environment variable by one application may get 
obliterated by another application storing different data to an identically named variable. 


With regard to the first problem, all that can be said is that due caution should be observed. Otherwise, 
your application may earn itself a bad name. 


With regard to the second problem, what is evidently required is some kind of naming convention. 


For a full discussion of environment variables see the paragraphs preceding p_getenv in the Plib 
Reference manual. 


1-4 


1 SERIES 3 PROGRAMMING OVERVIEW 


Avoid $ signs 


The 's' sign is used in names of environment variables created and manipulated by Psion system 
software. 


All external applications should completely avoid using environment variables with 's' signs in them - 
unless they first secure the agreement of Psion. 


The plan is to extend the use of 's' to mean, not just "used by Psion", but rather "licensed by Psion". 
Interested software developers who contact Psion will be given a short identifier - for example, "$175". A 
company which receives this identifier could then create environment variables with names such as 
"S$17S$table" OF "$17$ma", secure in the knowledge that no other responsible developer will also use these 
names. 


In conclusion, '$' signs should be avoided in all cases; even where approved by Psion, environment 
variable names should include 's' signs only in their identifier region. Thus a name of "sas17s" would 
not be allowed. Environment variables can of course continue to have "simple" names, such as "table" 
and "ma", but in this case, the chance of a name clash remains. 


Series 3 family compatibility 


Series 3/Series 3a/Workabout compatibility 


All Series 3 applications are fully compatible with the Series 3a and Workabout. These two machines 
automatically recognise such applications and run them in compatibility mode - both the icon, as 
displayed on the system screen, and the display are expanded linearly by a factor of two in each 
dimension. 


In fact an application that wishes to use the full screen capabilities of the Series 3a or Workabout must 
explicitly turn off the compatibility mode by calling the wcompat ibilityMode function - see the Window 
Server Reference manual for further details. 


An application can identify which machine it is running on - using a call to p_geticd - see the Plib 
Reference manual for details, and Compatibility in the General Programming Manual for an example. 


Thus it is quite feasible to write an application that runs on the Series 3, Series 3a and the Workabout, 
using the screen of each machine to the full. However, care should be taken to ensure that the application 
does not use any Series 3a or Workabout specific features when running on the Series 3 - the grey scale 
or, on the Series 3a, the improved sound facilities for example. The Workabout also has different 
keyboard scan codes from the other members of the Series 3 family, (see Hardware Management, in the 
EPOC OSS System Services manual). 


Compatibility with Series 3c and Siena 


Programs written for the Series 3 


All Series 3 programs can be expected to run without modification on both the Siena and the Series 3c. 
The programs will run in compatibility mode, as they do on the Series 3a. 


Programs written for the Series 3a 
Most types of program will run without modification on the Series 3c. 


It is likely that most Series 3a programs will need some modification, to take account of the smaller screen 
size, before they will run on the Siena. Menus and dialogs in Series 3a programs will, in general, be too 
wide and will need to be reorganised and/or reworded. Applications that use a sophisticated layout in their 
display are likely to need extensive modification before they can be used on the Siena. 


Series 3a applications written using the Hwif library, and which use grey lines in their menus, will need to 
be relinked with a suitably modified Hwif library before they will run on either the Siena or the Series 3c. 
This incompatibility is associated with the introduction of small fonts for dialogs on the Workabout and 
Siena. 


Hwif programs that are compiled and linked with a modified Hwif library (see the Programming in Hwif 
chapter of this upgrade document) that is supplied with the upgrade software can run on the Series 3, 
Series 3a, Series 3c, Workabout and Siena - provided, of course, that their displays are tailored to the 
various screen sizes and graphics capabilities of these machines. 


CHAPTER 2 


COMMUNICATING WITH THE SYSTEM SCREEN 


Introduction 


An important aspect of the Series 3 is the way all the built-in applications communicate with the System 
Screen application (also known as the Shell application): 


e The name of any file currently open is displayed in bold in the file list in the System Screen 
e This name is also displayed in any status window shown 


e Ona request from the System Screen, an application can close itself down tidily, saving any 
changes to file as appropriate 


e =©Alternatively, applications can be requested to switch files, to change which file they are 
currently editing. 


Applications use two mechanisms to communicate to the Series 3 OS their preferences concerning file 
switching, as well as the name of the file they are currently editing: 


e some data is written at compile time into a shell data file (.shd file) that is linked into the 
application's .app file; this data includes the expected extension of any files to be edited, and the 
default directory for these files, as well as the more basic point of whether the application is file- 
based at all 


e other data can be written at run time to various reserved Epoc statics; these include the full path 
name of the file currently being edited. 


Creating .shd files 
The format of .ms files 


The shell data of an application (see above) is expressed in source form in a file that typically has 
extension .ms. For example, the contents of a file tele.ms could be: 


Tele.TEL 
\TEL\ 
3 


Running the tool makeshd as follows 
makeshd tele 
would produce the file tele.shd from tele.ms (barring syntax errors in the .ms file). 


The .shd file can then be combined into the final .app form of an application as discussed in the previous 
chapter. 


The first line in a .ms file has general form 
<Name>[<.EXT>] 


with the extension .&xT only being present for file-based applications. In that case, .ext defines the 
default extension for the application. In all cases, Name is the so-called public name of the application. 
This must be a valid file name, that is, it must start with a letter and not exceed eight characters. 


SERIES 3/3A PROGRAMMING GUIDE 


The second line in a .ms file gives the default directory for an application. This can be left blank for non 
file-based applications. For example, the .ms file for the built-in Time application could be 


Time 
8000 
with the second line left blank. 


The third line in a .ms file gives the type of the application (sometimes called the type number of the 
application). 


A .ms file can have fourth, fifth, sixth ... lines, but only if 2000 has been added to the application type, so 
that the application has multi-lingual shell data (see below). 


At present, there is no scope for the inclusion of comments in a .ms file. 

Note that the entire contents of a .ms file is case sensitive. Eg an application with first line 
RunGame 

in its .ms file will have public name RunGame, whereas an application with first line 
Rungame 


in its .ms file will have the distinct public name Rungame. Further, the default extension and default 
directory should always be given in upper case (otherwise the file list may fail to display any files). 


Default extension 
The significance of the default extension for a file-based application is as follows: 


e Files will be shown in the file list for the application in the System Screen only if their extension 
matches the default (with the exception that files are always shown - in bold - if they are 
currently the open file of an application) 


e The System Screen will pass the specified default extension to the application as part of its 
command line, when it is started 


e Typically, applications will use filename selectors in dialogs which hide extensions matching the 
default (eg showing Tele rather than Tele.tel), and may even omit other files from the initial list 
presented. 


Public name 
The significance of the public name of an application is as follows: 


e This is the name by which the System Screen refers to the application, eg when confirming that 
the application be "Removed", or when allowing an application button to be assigned to the 
application 


e This name will be displayed in the file list for the application, in the System Screen, in any case 
when the list would otherwise be empty. 


The contents of Name [.EXT] must in all cases be a valid filename, ie Name cannot exceed eight characters 
in length, xT cannot exceed three characters in length, and there must be no embedded spaces (etc). 


Default directory 


Files will be shown in the file list for the application in the System Screen only if they are located in a 
directory whose name exactly matches the default (with the exception that files are always shown - in 
bold - if they are currently the open file of an application). 


Default directories for applications are usually top level, as in \TEL\. However, they can equally well be 
subdirectories, as in \TEL\PRIVATE\, with the limitation that the total length cannot exceed 20 characters 
(this count including a terminating zero at the end of the directory path name). 


Application type numbers 
The significance of an application's type number is as follows: 


e A type of 0 means that the application a) will have no file list when installed in the system screen 
- instead there will be only one entry, giving the public name of the application b) will receive no 
Switchfile commands from the System Screen and c) no filename will be specified in the 
command line. Type 0 applications can have only one copy running at any one time. 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


A type of 2 is used to restrict a file based application such that only one copy can run at any one 
time - this is the case for the built-in World application. In contrast see types 0 and 3. 


A type of 3 means that the application a) will have a file list when installed in the System Screen, 
and b) can receive Switchfile instructions. More than one copy of the application can be run at 
any one time. 


A type of 4 means that the application will have a file list in the System Screen, but will never be 
sent Switchfile instructions: however, it should read the command line on its start up (an example 
is the built-in RunOpl application) 


Finally, a type of 5 means that the application is a pure file list application, ie not a real 
application at all, but just an icon to group together various applications or utility programs (like 


the built-in RunImg icon) - see below for more details. 


The application's behaviour may be further modified by adding one or more of the following values to the 


type number: 


8000 


4000 


2000 


1000 


100 


80 


prevents Switchfile messages of the Create sort being sent to the application 
(this makes sense for an application such as a file dumper, which can dump the 
contents of existing files, but cannot meaningfully create the file it is going to 
dump) 


prevents the application being sent Shutdown messages - this will also prevent 
the application being Killed from the System Screen (but not, for example, 
from the Spy application released as part of the SDK) 


indicates that the application's .ms file contains public names for more than one 
different language version (see below) 


indicates that the .pic file contains a 48 by 48 Series 3a icon (preceded by a 24 
by 24 icon if the application is to run on the Series 3 as well as the Series 3a). 
The Series 3 does not recognise this flag and will simply read the 24 by 24 icon 
if present. 


the application should not be sent an exit message so that, for example, 
pressing DELETE acts as Kill application. The Series 3 does not recognise this 
flag. 


on selecting "Create new list" from the System Screen, the resulting dialog box 
will contain an extra line, for specifying Text editor or Word processor type. 
The Series 3 does not recognise this flag. 


Multi-lingual forms of .ms files 


Suppose the Data application were to be translated into French, German, and Italian, and that its public 
names in these languages were to be Fiche, Daten, and Archivi, respectively. In that case, an appropriate 
.ms file would be as follows: 


Data.DBF 
\DAT\ 


2003 


Q1Data 
02Fiche 
O03Daten 
O5Archivi 


Here, the 2000 in the application type means that the remaining lines in the .ms file are each made up as 


follows: 


<language number><public name in that language> 


where language numbers are as documented in the p_get language part of the Plib Reference manual. 


The same rules apply to the public names for other languages as to the default public name defined in the 


first line of the .ms file. 


It is not possible to change the default extension or the default directory from one language to another. 


SERIES 3/3A PROGRAMMING GUIDE 


Applications which are intended to be capable of being run on either mono- or multi-lingual Series 3s 
should adopt the multi-lingual form of .ms file, and simply accept that the public name will be incorrect 
on mono-lingual machines. 


For multi-lingual machines, the System Screen uses the following rules to decide what the public name of 
the application should be: 


e the current language number is obtained by a call to p_get language 


e if this matches any language for which a public name is explicitly defined in the shell data, that 
public name is used 


e otherwise, the default public name is used (as given on the first line of the .ms file). 


For the sake of minimising the size of a multi-lingual .shd file as much as possible, it is evidently possible 
to omit any lines such as 


01Data 


which merely define the public name for some language to be what it would have been in any case, were 
this line omitted (in view of the contents of the first line of the .ms file). 


Pure file list applications 


If an application (Utils, say) has type 5, and the user presses ENTER when the highlight is over some file 
Xyz.abc in the file list for that application, the System Screen makes no attempt to run the application 
Utils. Rather, it assumes that Xyz.abc is itself a program, and attempts to run that. In other words, 
instead of executing Utils and passing the filename Xyz.abc as part of the command line, it executes 
Xyz.abc (without any command line being passed). 


For example, the .ms file for the built-in "application" RunImg is as follows: 


Runimg.IMG 
\IMG\ 
8005 


This means that the file list for RunImg lists .img files from \VMG\ top-level directories - each of which are 
program files. 


Note that unless the utility programs cooperate in some limited way, when run they will be listed (in bold) 
under the RunImg icon, rather than under any other pure file list icon. This is explained in the section 
below on the Epoc reserved static DatProcessNamePtr. 


In practice, the simplest way to create another pure file list application is probably to use the technique of 
aliasing, as discussed immediately below, to alias RunImg. 


Aliasing applications 


Some file-based applications may end up with large file lists. It may be desirable to separate a file list into 
two or more separate lists, for example (for the Word application) all correspondence going in one file list, 
all poetry in another, and so on. These file lists could be distinguished, on the System Screen, by having 
distinct icons, and different application buttons could be used to cycle round running instances of these 
tasks. 


Going further, it may be desirable for the behaviour of the application to alter, depending on which type 
of file is open. For example, the behaviour of the built-in text editor is different for .wrd files (when the 
application is seen as Word) from .opl files (when the application is seen as Prog). 


The concept of aliasing an application is designed to meet these requirements. For each required new file 
list, an alias file (als file) should be installed in the System Screen. In practice the user can do this on the 
Series 3a using the "Create new list" item from the "Special" menu (try it out ...). 


Broadly speaking, the contents of a .als file match those of a .shd file: the public name, default extension, 
and default directory are all defined, as well as the application type number. However, the .als file goes 
beyond the .shd file in that it also specifies: 


e the name of the application that is being aliased 


e (optionally) some alias info that the System Screen should pass to the application when it is run, 
via the command line, to configure its behaviour in some special way. 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


Creating .als files 


An .als file is produced from a .ma file and a .pic file by running the tool makeals. The three files all 
have the same root name (ie disregarding the extensions). For example, the command 


makeals letter 
produces the file /etter.als from letter.ma and letter.pic. 
The .pic file is the icon to use. The process of creating .pic files is discussed in the previous chapter. 


The .ma file is a source file similar in format to a .ms file. For example, the contents of a file letter.ma 
could be: 


Letter.let 
\WRD\LET\ 
3 

Word 


in which there is a fifth line which is blank (makeals will give an error if the fifth line is omitted 
altogether). 


Just as there are multi-lingual forms of .ms files, there are also multi-lingual forms of .ma files. However, 
in practice these are of limited use, for technical reasons. This is discussed in its own section (which the 
majority of readers can skip) at the end of this chapter. 


The first three lines of a .ma file correspond exactly to those of a .ms file. The fourth file is the public 
name of the application to alias. The fifth line gives the alias info, which is a zero-terminated string of 
up to eight characters. 


In most cases, the application type will be the same for the alias file as for the application being aliased. 
However, the public name, the default extension, and the default directory are all commonly varied. 


Note that the public name of an alias must differ from that of the application it is aliasing. Otherwise, 
seeking to install the alias in the System Screen will have no effect (it is not possible to have two different 
file lists, each with the same public name). 


Incidentally, no check is made, at the time of installing an alias file, that the application it aliases is itself 
currently installed. This check is only made when an instance of the alias is to be started. 


Active aliasing and passive aliasing 


In theory, all applications are capable of being aliased, without them needing to make any conscious 
provision for this possibility. This is known as passive aliasing. 


Other applications pay explicit attention to any alias info that may be passed to them on their command 
lines, and adjust their behaviour according to the contents of this info. This is known as active aliasing. 
An example of active aliasing is that of the built-in text editor, as described in the following section. This 
is the only one of the applications built into the Series 3 and Series 3a that supports active aliasing. 


Any other program that supports active aliasing is free to interpret alias info passed to it in any way that it 
wishes. There is no obligation to mimic the detailed rules obeyed by the text editor. 


Active aliasing in the built-in text editor 


If the alias info is a null string, the text editor enters Word mode, with multi-level outline facilities, styles 
and emphases, and so on. 


Note that it is not unreasonable for an alias to define null alias info. This allows the creation of aliases of 
the text editor that behave in exactly the same way as the built-in Word application, but differ from each 
other in terms of their default extensions, default directories, and/or public names. 


If there is any non-null alias info, the text editor enters one of a number of other modes, with the mode 
depending on the first character of the alias info. Some of these modes are not available on Series 3 
machines. At the time of writing, the allowed first characters and the corresponding modes are: 


OPL program editor 

Comms script program editor 

Plain text editor (not Series 3) 

Word processor with custom template (not Series 3) 


Nunn O 


2-5 


SERIES 3/3A PROGRAMMING GUIDE 


The program editor mode is available on all machines. In this mode there is no access to the style and 


emphasis subsystems, the corresponding menu commands being replaced by options to "translate", "run", 
"show error" and set "indentation". 


In this mode, the first letter of the alias info denotes the nature of the program that is being edited. It 
actually identifies the program to invoke to effect any "translate" and (possibly) "run" commands from the 
user. The generic name of this program is sys$prg?.img, with the question mark being filled in from the 
first letter of the alias info. Thus the Prog alias has 'o' for the first letter of its alias info, and so the OPL 
translate/run program sys$prgo.img is used. In contrast, the Script editor from the communications ROM 
has 's' for the first letter of the alias info, so that the program sys$prgs.img is used. 


In program editor mode the second letter of the alias info should be 'R' if the program is of a type that 
understands "run" instructions in addition to "translate" ones. Any other second character disables the 
"run" command option. The following three letters (e.g. 'opo' or 'sco') denote both the expected file 
extension and the expected top-level directory where any translated output will by default be placed. (This 
information is used by the editor when offering the user a suitable filename to "run"). 


On the Series 3a a final '*' character may be added to the alias info. This has the effect of adding an "S3 
Translate" menu option. 


The remaining modes are not available on Series 3 machines. 


Alias info that consists of a single '$' character selects a plain text editing mode. In this case the 
program-related menu options are suppressed, with only an "indentation" option being offered. 


A variant on the Word mode is set by alias info that consists of a single '/' character. This behaves in a 

similar way to the Word application, with the exception that a specific template file is loaded whenever a 
new file is created. The template must have the same name as the aliased application and must be located 
on the current drive at the time the new file is created. Thus, an alias created from the following .ma file: 


Letter. LET 
\LET\ 

1083 

Word 

/ 


would, on creation of a new file, automatically load the template file \wdrVetter.wrt, provided it exists on 
the current drive. Note that, in this mode, the value 80 must be added into the application type number. If 
it is not, the automatic loading of the template is disabled. 


How aliasing works 


Part of the mechanism of aliasing is handled by the System Screen: 
e creating a new file list 
e listing the appropriate files in the new file list 
e allowing the user to assign a new application button to the new file list 


¢ creating a suitable command line to pass to the relevant application, when the user chooses to 
start an instance of the alias (by pressing ENTER on an entry in the file list). 


However, other parts of the mechanism of aliasing rely on the application paying suitable attention to the 
details of the command line passed to it. Failure to do this will diminish the effect. 


Thus even passive aliasing relies on some cooperation from the application being aliased. For example, 
an application that is determined that it knows what its public name is (say Word) and which writes this to 
DatProcessNamePtr (see below) in all cases, despite any different public name being passed to it on the 
command line, will frustrate the intent of any aliasing application: 


e¢ any application button assigned to the alias by the user will be ineffective 
¢ running instances of the alias will appear (in bold) in the wrong file list in the System Screen. 


This is just one reason why all serious applications should analyse the command line passed to them, as 
part of their initialisation procedures. 


There are routines in both the Hwif library and the Hwim dyl to assist in analysing the command line. 


2-6 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


Epoc reserved statics 


The values of the Epoc reserved statics DatProcessNamePtr, DatLocked, DatStatusNamePtr, and 
DatUsedPathNamePtr all have special significance for Series 3 applications. The values of these variables 
for different applications are read at various times by the System Screen and also by the Window Server. 
An application which fails to write suitable data to these statics may find that: 


e an incorrect name is displayed in any status window shown in the application 
¢ instances of the application are shown in the wrong file list in the System Screen 


¢ Shutdown or Switchfiles messages arrive at inopportune moments from the System Screen (see 
below for more on these messages) 


¢ assigning an application button to the application in the System Screen has no effect. 
In general, applications should write to these reserved statics: 

e on initialisation (after having analysed the contents of their command line) 

e whenever a new file is opened 

e whenever the application is about to go "busy" over an extended period of time. 


There are routines in both the Hwif library and the Hwim dyl that assist with keeping these reserved 
statics up to date. 


While debugging using the Sibo Debugger, the values of reserved statics can be determined by using the 
"Magic Statics" menu command. 


DatProcessNamePtr (0x22) 


This static is read by the System Screen when deciding which file lists bolded running applications should 
be placed into. It is also read by the Window Server when deciding which action to take when an 
application button is pressed. Finally, it is read by the System Screen in response to any "Quit 
application" menu commands, to determine how to implement this request (ie how much cooperation the 
System Screen might expect from the application). 


The way the file lists are built in the System Screen is as follows: 
e for each list, the set of all eligible files is compiled; these will all be displayed non-bolded 
e then for each running application, it is decided which file list the application belongs to 
e this involves reading the value of DatProcessNamePtr for the application 
e further, for each running application, the name of the file currently open (if any) is decided 


e this involves reading the value of patusedPathNamePtr for the application (and possibly also the 
value of patProcessNamePt r) 


e if this name matches any entry in the file list, that entry is removed (so that it is no longer 
displayed non-bolded) 


e the name of the open file is added to the list, in bold. 
Clearly, the lists will be misleading if the running application is assigned to the wrong list. 
The rules for assigning a running application to a particular file list are straightforward: 
e the preferred public name of the application is read from patProcessNamePtr 
e if this matches the public name of any existing file list, the application is assigned to that list 
¢ otherwise, the application is assigned to the RunImg list. 


More on the file lists in the System Screen 


Incidentally, any entry starting with Sys$ is never displayed in any file list. Further, the name Link is 
never displayed in the RunImg list. These rules prevent the display of private system processes within the 
System Screen file lists. 


SERIES 3/3A PROGRAMMING GUIDE 


Additionally, files with the "hidden" attribute set are never displayed in a file list in the System Screen - 
unless the file is open within an application (in which case it will be displayed in bold). 


In order to check for the existence of hidden files or file starting with Sys$ in a directory, the user should 
press TAB to enter "directory" mode of the System Screen. 


It is also possible to task to an application whose open file starts with Sys$ by repeatedly pressing the 
SHIFT+SYSTEM key combination, which tasks round all running applications (that are clients of the 
Window Server). 


Assigning application buttons 


Suppose that the user has installed the application Te/e, and has assigned the application button 
CONTROL+WORD to it. The following is what happens when the user presses CONTROL+WORD: 


e at all times, the System Screen maintains a data structure associating each of the 14 possible 
application buttons to public names of applications 


e the address of this data structure, within the System Screen dataspace, is known to the Window 
Server (in fact it is kept at Datapp1) 


¢ when CONTROL+WORD is pressed, the Window Server consults this data to determine the public 
name that is currently associated with this application button (ie Tele in this example) 


e the Window Server next checks whether the public name of the current foreground application 
matches Tele, reading the public name from DatProcessNamePtr 


e if so, this application is sent a special key-press event, with keycode value equal to W_KEY_MODE 
(as defined in wskeys.h) - unless the SHIFT modifier is also held down, in which case the 
algorithm continues as below 


e¢ otherwise, the clients of the Window Server are scanned in current task order, to see whether any 
can be found with the required public name 


e if any can be found, this is made foreground 


e failing this, a message is sent to the System Screen to position, if possible, to the file list 
associated with the given public name 


e if no such file list exists, the System Screen beeps and gives a suitable error message. 


The crucial point in this is that, once again, the public name of the application has to be written to 
DatProcessNamePtr. 


Incidentally, it is now clear why pressing the CONTROL+SYSTEM key (assigned to RunImg), or any other 
application button assigned to a pure file list application, often fails to have the desired effect (of bringing 
to foreground a running application listed in the relevant file list). The point is that these applications are 
generally run without any command line being passed to them, and so they cannot set up a suitable value 
at DatProcessNamePtr merely by analysing their command lines. 


Also note that the assigned buttons differ in one aspect of their behaviour depending on the machine used. 
Consider an application, the built-in database say, that is currently running in the foreground. On the 
Series 3 pressing the Data button would change the application from search mode into change mode, and, 
on a second press, back into search mode. On the Series 3a pressing the Data button has no effect when 
there is currently only one copy of the application running. However when multiple copies are running, 
then pressing the Data button has the effect of sequentially bringing each copy into foreground - 
simultaneously holding down the shift key reverses the order of bringing into foreground. Try out the Data 
button while running multiple copies of the database ... 


DatUsedPathNamePtr (0x3e) 


The Epoc reserved static DatUsedPathNamePtr is read solely by the System Screen, which assumes that if 
it is non-null for an application, DatUsedPathNamePtr points to a full path specification of the file 
currently open in the application. As described above in the section on DatProcessNamePtr, these 
filenames are used when generating the file lists in the System Screen: 


e any open file matching an entry in the non-bold section of the file list replaces that entry 


e the filename is parsed and rearranged, eg from the form LOC::A:\WRD\SHOPPING. WRD into 
Shopping[A]. 


2-8 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


In case DatUsedPathNamePtr 1s null, the value of the string at patprocessNamePtr (if any) is used instead: 
failing that, the process name (as returned by p_pname) is used. 


Initially, the name of the open file is part of the command line (see below). However, when this has to be 
changed - either as a result of an Open or Save as command inside the application, or in response to a 
Switchfile request from the System Screen - a new buffer has to be used for this purpose. (The command 
line buffer is sized to precisely the right length needed for the initial file.) 


Typically, file-based applications will maintain a permanent buffer, of length p_rnames1zz, to store any 
change in the name of the file open. Once the new name has been copied into this buffer, a call such as 
hSetUpStatusNames (described below) should be made, to adjust all Epoc statics as appropriate, including 
DatUsedPathNamePtr. 


DatStatusNamePtr (0x3c) 


The Epoc reserved static pat StatusNamePtr is used to determine which text string should be displayed as 
the name of the application in any status window shown for that application. 


If non-zero, this is assumed to point to a string giving the text to use, with the text being clipped at the 
first dot encountered, and in any case after eight characters. The text is also converted into standard 
capitalised form. Thus if patstatusNamePtr points to "DIARY.acN", the text Diary will be displayed in 
the status window. 


The rules for what text to display when pat statusNamePtr is null are the same as those employed when 
DatUsedPathNamePtr is null (see above). 


DatLocked (0x3a) 


When the user attempts to terminate an application using the "Quit application" command in the System 
Screen, or to change the file currently open, by pressing ENTER on another entry in the file list for that 
application, the System Screen checks the value of the Epoc reserved static Dat Lockea for that application. 


If this is non-zero, a message Application is busy 1s displayed, and the user's request is refused. 


Applications which enter a state in which they are unable to respond to such requests from the System 
Screen should accordingly set patLocked to TRUE. Good programming practice dictates that DatLocked be 
set back to FALSE again as soon as possible afterwards. 


The Series 3 command line 


The command line communicates the following information to a Series 3 application about to start: 
e the public name of the application 
e the default extension for files used, if any 
e any alias information specified in an alias file 
e the full path name of the file to open, if any 
e whether this file should be opened or created anew 
¢ exceptionally, whether the application is to connect to the Window Server in background. 


When a program starts, its command line is placed in an allocated cell within the heap of the application, 
with the address of this cell being written to the Epoc reserved static DatcommandPtr. See the section on 
p_execc in the Plib Reference manual for some general information about patcommanaPtr. 


The command line for any Epoc program always starts with a zero-terminated string given the full path 
name of the process being run. The byte after this gives the length of any following data. Ordinarily, 
when referring to "the command line", it is this latter data that is in mind. 


For example, suppose the user presses TAB inside the Prog file list in the System Screen, navigates using 
the file selector to loc::m.\dat\data.dbf, and then presses ENTER. The full command line passed to the 
application thereby chosen (Word) is as follows: 


ROM: :WORD.APP<0><29>O0Program<0>.OPL OROPO<0>LOC: :M: \DAT\DATA.DBF<0> 


2-9 


SERIES 3/3A PROGRAMMING GUIDE 


The <29> immediately following the zero at the end of the first zero terminated string indicates that the 
remainder of the command line is 0x29 bytes long - as is indeed the case. 


The next byte after this is the so-called command byte: 
¢ acommand byte of 'o' means, for a file-based application, that a named file is to be opened 
¢ acommand byte of 'c' means, for a file-based application, that a named file is to be created 
¢ acommand byte of 'D' means the application is to connect to the Window Server in background. 


A command byte of 'p' arises only for the built-in applications, and is not considered in the remainder of 
this documentation. (When it does arise, it is handled automatically by code in hwim.dyl, which silently 
translates it into one of the other two cases.) 


Following the command byte, there is a zero-terminated string giving the public name of the application. 


After this comes another zero-terminated string, containing both the default extension and (if present) the 
alias info. The alias info, if present, is separated from the default extension by a space. 


Finally, yet another zero-terminated string gives the full path name of the file to open or create. 
With regard to the above example: 

e The command byte of the application is '0' 

e The public name of the application is "Program" 

e = The default extension is ".oPL" 

e = The alias info is "oRopo" 

e The name of the file to open is "Loc: :M:\DAT\DATA.DBF". 


Summary of command line format 


In summary, the format of the command line of a Series 3 application is as follows: 


<command byte><public name><0>[<default extension>[<space><alias info>]<0><full 
pathname><0>] 


Supplying a command line from the SIBO Debugger 


Ordinarily, applications are executed from the System Screen, which automatically constructs a suitable 
command line. 


When executing an application from the Debugger (or from an alternative "Shell" program), the 
command line has to be supplied explicitly. Some examples follow: 


@ SDBG TELE "CTELE",0,"LOC::M:\TEL\TELE.TEL" - debug the application fele giving it the public 
name Tele, and have it Create the file Loc: :M: \TEL\TELE. TEL on start up 


@ SDBG DA2 "ODAYS",0,"LOC::A:\ANN\DAYS.ANN" - debug the application da2 giving it the public 
name Days, and have it Open the file Loc: :A: \ANN\DAYS.ANN on start up 


@ SDBG JO1 "CJOKER", 0,0 - debug the application jo/ (which is not file-based), giving it the public 
name Joker. 


These examples take advantage of the following processing of the command line by the Sibo Debugger: 


¢ parameters entered as a string ("...") are passed on to the program with a zero terminating the 
string 


¢ parameters given in numeric form (eg 0) are passed on to the program as single bytes 
e adjacent parameters separated by commas are concatenated. 


One drawback of the command line processing of the Sibo Debugger should be pointed out: everything is 
automatically upper-cased. This means that if an application button has, for example, been assigned to 
the public name Days, no application run in this way from the Sibo Debugger will ever be tasked to as a 
result of the user pressing the corresponding application button (for public names are in general case- 
sensitive). 


2-10 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


From command line to reserved statics 


As mentioned earlier in this chapter, an application should analyse its command line on start-up, and 
should write various values from this command line into Epoc reserved statics as a result. 


As an example of how this could be done, there follows the source code for two Hwif routines: 


GLDEF_C VOID hSetUpStatusNames (TEXT *pb) 


{ 
TEXT buf [P_FNAMESIZE]; 


P_FPARSE crk; 


DatUsedPathNamePtr=pb; 

p_fparse(pb,0, &buf[0],&crk); 

DatStatusNamePt r=pb+P_FSYSNAMESIZE+crk.devicetcrk.path; 
} 


GLDEF_C INT hCrackCommandLine (VOID) 


{ 
INT ret; 
TEXT *pb; 


pb=DatCommandPtr; 
pbt+=p_slen (pb) +1; 
if (!*pbt+) 
ret=0; 
else 
{ 
ret=(*pbtt) ; 
DatProcessNamePtr=pb; 
pbt+=p_slen (pb) +1; 
pb+=p_slen (pb) +1; 
if (*pb) 
hSetUpStatusNames (pb) ; 
else 
DatStatusNamePtr=DatProcessNamePtr; 


} 


return (ret); 


} 


For details of the patcommandptr and other reserved statics see the Processes and Inter-Process 
Messaging chapter of the Plib Reference manual. 


Applications that disregard their command line 


Simple applications - especially those that are not file based - have no need to pay any attention to the 
command line passed to them by the System Screen. In this case, the various relevant Epoc statics are left 
at their default (zero) values. This fact is picked up by the System Screen and by other parts of the OS, 
with the following results: 


e The name displayed in any status window and in the file list in the System Screen is just that of 
the application .app file 


e If the user requests the application to be shut down, from the System Screen, the application is 
shut down by the OS, without the application itself being informed of this fact (just as if the user 
had selected the Kill option in the System Screen). 


In case an application wishes to do its own processing in response to a Shutdown request issued by the 
user in the System Screen, it must therefore make a call to a routine such as hcrackCommandLine during 
its initialisation. This is true even if the application is not file-based. 


One final drawback of an application not processing its command line is that users will be unable to 
assign application buttons with any effect to that application. Suppose a user assigns CONTROL+WORLD to 
a version of the Spy application, for example, that fails to write anything suitable to patProcessNamePtr. 
If the user subsequently presses the key combination CONTROL+WORLD, the Spy application will fail to be 
brought into foreground - thus spoiling the whole purpose of assigning the application button. 


2-11 


SERIES 3/3A PROGRAMMING GUIDE 


Creating directories when required 


In contrast to file selectors on other systems, those on the Series 3 allow users to specify paths that do not 
yet exist. This can happen fairly commonly, for example as follows: 


e The user inserts a brand new solid state disk into drive A 
e =A Save as or New file menu command is invoked 

e The user adjusts the disc selector to this new disk 

e The user types eg "Backup" into the filename editor. 


Then assuming the default directory for the application is \D/R\ and the default extension is .EXT, the 
filename returned to the application is 


LOC::A\DIR\BACKUP. EXT 
even though the directory \D/R\ does not exist yet, on the specified disk. 


It is the responsibility of application programs to test for this case and to create the required directories. 


Messages from the System Screen 


Shutdown messages 


Series 3 applications can receive Shutdown messages from the System Screen, as an instruction to shut 
themselves down tidily, saving any changes to file as required. 


These messages can arise when the user presses DELETE while highlighting a running task in the System 
Screen. However, as mentioned above, if the application has set its Dat Locked to TRUE, the System Screen 
instead presents an Application is busy message. 


Incidentally, applications are sent Shutdown messages only if they have a non-zero value of 
DatProcessNamePtr. The System Screen assumes that any application that has left this Epoc reserved 
static at its default (zero) value is unlikely to be prepared to respond to Shutdown messages. In that case, 
the System Screen instead calls p_pterminate to terminate the application. 


Finally, note that any application which has 4000 included in its application type number will never be 
sent a Shutdown message from the System Screen; instead, the System Screen will display the message 
Cannot quit application. Note that this blocking mechanism was designed for internal use only, and 
should not be used without good reason. 


Switchfiles messages 


Series 3 applications can receive Switchfiles messages from the System Screen, as an instruction to close 
down their existing open file, and to open or create another one. 


These messages can arise when the user presses ENTER while highlighting a file within that application's 
file list in the System Screen. However, if the application has set its DatLocked to TRUE, the System 
Screen instead presents an Application is busy message. 


Switchfile messages will only ever be sent to applications with basic type number 2 or 3. Applications 
whose type numbers include 8000 can receive Switchfile messages of the Open sort, but not of the Create 
sort. 


How messages from the System Screen are received 


There are two parts to an applications receiving a Shutdown or Switchfiles message from the System 
Screen: 


e the application receives notification that some message from the System Screen has been sent 
e the application calls wGet command to determine the contents of the message. 


In turn, the initial notification can be received in either of two ways, depending on whether the 
application is receiving events from the Window Server directly (by calling wcetEvent or a variant), or as 
"extended keypresses" via the console device (as occurs for example in Hwif programs): 


e for the protocol in the first case, see the discussion on wM_comMaND in the Window Server 
Reference manual 


e for the protocol in the second case, see the discussion on P_EVENT_READ in the Console chapter of 
the I/O Devices Reference manual. 


2-12 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


In either case, the initial event prompts the application to call weet command, to obtain the so-called new 
command line giving more details about the event. 


Contents of the new command line for System Screen messages 


The parameter passed to wGetCommand must be the address of a buffer having at least p_FNamEs1zE (128) 
bytes. The new command line is written into this buffer. 


The first byte of the new command line will be one of 'x', '0', or 'c!: 


a means the command is a Shutdown message 
‘oO! means the command is a Switchfiles message, with a specified file to be opened 
mG! means the command is a Switchfiles message, with a specified file to be created. 


In the case of Switchfiles messages, the remainder of the new command line gives the full pathname of the 
file to open or create. 


An example of code that responds to notification of a message from the System Screen is as follows: 


LOCAL_C VOID ProcessSystemCommand (VOID) 


{ 
UBYTE buf [P_FNAMESIZE]; 


wGetCommand (&buf[0]); 

if (buf [0]=='X"') 
ExitApplication(); 

SavelfChanged() ; 


if (buf [0]=='C') 

CreateNewFile (&buf[1]) /* remainder of message is ZTS of file to create */ 
else /* buf[0]=='0' */ 

OpenExistingFile(&buf[1]); /* remainder of message is ZTS of file to open */ 


} 
Other possible types of messages 


At the time of writing, the command byte of new command lines (as read by wGet commana) is restricted to 
one of the three values 'x', '0', or 'c'. It is possible, however, that some future application might send 
messages to other applications having different command bytes. 


These messages would be sent by means of the wSendcommana function, as described in the Window Server 
Reference manual. (Note that these messages are not the same thing as IPC (inter-process 
communication) messages; nor are they the same as object-oriented messages.) 


In order to be future proof, an application should arguably test explicitly for all expected values of the 
command byte, and should ignore values other than those expected. The above code fragment would 
therefore need to be modified. 


Multi-lingual aliasing of Word.app 


This section can be omitted by all readers, except those who wish to write a multi-lingual alias of 
Word.app. 


The reason why .als files as created by makeals.exe cannot be used in this case is that these files have to 
contain the public name of the application being aliased. However, the public name of Word.app can vary 
from language to language, and there is no facility to track this within an ordinary .als file. 


To surmount this problem, the .als file can be re-written as a program. 


2-13 


SERIES 3/3A PROGRAMMING GUIDE 


For example, the following code provides a successful multi-lingual alias for Word.app: 


2-14 


#include <p_std.h> 
#include <p_file.h> 
#include <epoc.h> 


#include <rscfile.xg> 


#include <p_sys.h> 


#define R_STRARRAY_APPNAMES 78 


GLREF_D UBYTE *DatCommandPtr; 


GLDEF_D TEXT olibDyl[]="OLIB.DYL"; 
GLDEF_D TEXT shellImg[]="ROM::SYSSSHLL.IMG"; 
GLDEF_D TEXT wordNameFmt []="ROM::%S.APP"; 


GLDEF_D TEXT aliasInfo[]={'S','R','S','C','0'}; 


LOCAL_C TEXT *skipStr(TEXT *p) 


{ 
return (p+p_slen(p) +1); 
} 


#pragma save, ENTER_CALL 


LOCAL_C INT getWordFspec ( 


/* 


Get full file spec of Word.APP using shell's resource file. 


Returns 0 if successful, leaves if error. 


ay 


TEXT *fSpec) /* To receive name */ 
{ 

TEXT *pAppNames; 

VOID *rsc; 

HANDLE cat; 


p_findlib(&olibDy1l[0],é&cat) ; 
rsc=f_newlibh(cat,C_RSCFILE) ; 

p_send3(rsc,O_RS_INIT, &shellImg[0]); 

p_send4 (rsc,O_RS_READ, R_STRARRAY_APPNAMES, &pAppNames) ; 
p_atos (fSpec, &wordNameFmt [0], skipStr(pAppNames+1)); /* 
p_free (pAppNames) ; 

p_send2 (rsc,O_DESTROY) ; 

return (FALSE) ; 

} 


Copy to 2nd string */ 


2 COMMUNICATING WITH THE SYSTEM SCREEN 


#pragma restore 


GLDEF_C VOID main(VOID) 


TEXT fSpec[P_FNAMESIZE]; 

UBYTE comBuf [E_MAX_COMMAND_BUFFER+1]; 
TEXT *pCommand; 

TEXT *pAlias; 

TEXT *pEndAlias; 

TEXT *p; 

HANDLE pId; 

INT len; 


p=skipStr(DatCommandPtr) ; 
len=(*p); 
pCommand=(pt1) ; 


pAlias=skipStr (pCommand) ; 
pEndAlias=skipStr(pAlias)-1; /* Point to end 0 */ 


p=p_bcpy (&comBuf [0], pCommand, pEndAlias-—pCommand) ; 
p=p_bcpy (p, &aliasInfo[0],sizeof(aliasInfo) ); 
p_bcpy (p, pEndAlias, len- (pEndAlias-—pCommand) ) ; 


if ((pId=p_enter2 (getWordFspec, &fSpec[0]) ) <0) 


goto fail; 
if ((pId=p_execc (&fSpec[0],&comBuf[0],len+5))<0) /* Run Word */ 
goto fail; 
p_setpri(pId,p_getpri(p_getpid())-1); 
pid=p_presume (pId) ; /* Won't run till I've exited */ 


fail: 
p_exit (pId); 
} 


This program uses the fact that the filename of the Word.app application is always stored in the 78th 
resource within the resource file of the shell application. (Hence the #define of R_STRARRAY_APPNAMES aS 
78.) This resource actually contains an array of strings giving the filenames of the built-in applications, 
with the filename of Word.app as the second element in the array. 


See the chapter Resource Files in the Additional System Information chapter for background on creating 
and using an instance of the rscfile class. 


The program also analyses its own command line, and constructs a suitable one to pass on to Word.app. 
The detailed working of the program can be followed using the information given earlier in this chapter. 


2-15 


CHAPTER 3 


ENHANCED SOUND OUTPUT 


Introduction 


The Series 3 and Series 3a provide distinct sets of sound services. 


The Series 3 as supplied can emit only buzzer sounds, DTMF dialling tones, and simple alarm sounds. 
However, by loading a suitable device driver, such as SVDFRC.LDD, the machine can also be made to 
emit sequences of musical notes of variable duration, thus greatly extending its sound capabilities. The 
first section of this chapter describes use of the SVDFRC.LDD attached device driver from within a simple 
demonstration program. 


The Series 3a has considerably greater sound capabilities than the Series 3. In addition to emitting buzzer 
sounds, DTMF dialling tones and simple alarm sounds, the Series 3a can play simultaneously two 
sequences of musical notes, and can play and record digital sound files - for details of playing and 
recording digital sound files see the General System Services chapter of the Plib Reference manual. The 
second section of this chapter describes a simple program that demonstrates the playing of sequences of 
notes using the built-in snp: device driver. 


Warning: any attempt to load and use the SVDFRC.LDD attached device driver on the Series 3a is a 
serious error - the machine will in all probability hang, necessitating a soft reset. 


Sound on the Series 3 


Introduction 


This section explains how to create a wider range of musical sound output, via the loudspeaker, than is 
possible by merely using the Series 3's built-in snp: device driver. 


These services rely on a dynamic extension to the Series 3 operating system, known as a loadable device 
driver. 


With this device driver installed, strings of sound covering two octaves in semitone intervals can be 
generated. Control is also possible over the duration and loudness of the notes emitted. 


The sndfre and snddvr device drivers 


The chapter Example Device Drivers in the Additional System Information manual describes two different 
enhanced sound drivers, sndfrc.ldd and snddvr.ldd, from the point of view of how to write device drivers. 
The current chapter focuses on the question, not how to write these drivers, but how to use them. 


In fact, this chapter only considers the driver sndfrc.ldd, which is arguably the superior of the two. See 
Example Device Drivers for a discussion on how the two device drivers differ. 


Once this device driver file has been installed, a device with the name mus: can be opened by applications. 


Installing sndfre.ldd 


Any program which wishes to use the services of sndfrc.ldd needs to check, during its initialisation, that 
this driver has been installed. This is necessary because, in contrast to some other device drivers such as 
the serial port device driver and the basic sound device driver, the mus: device driver is not built into the 
ROM of the Series 3. 


SERIES 3/3A PROGRAMMING GUIDE 


The way to check the device driver is loaded is to make the call 
p_loadldd("SNDFRC.LDD") ; 
where the full path of the ./dd file can be given. (The ./dd file has to be copied onto the Series 3.) 


The return values zero and &_FILE_Ex1StT can both happily be ignored. Other errors are more serious - 
they probably mean that the file sndfrc.ldd cannot be located. In this case, the program cannot continue (at 
least, not as according to its original intention). 


Opening a channel to MUS: 


Another pre-requisite to using the services of sndfrc.ldd is to open a channel to uus:. This is done in the 
standard manner for all i/o devices: 


p_open (&handle, "MUS:",-1); 


If this call is successful, it writes back the handle of the channel established to the device driver. All 
subsequent requests from the program (until such time as the channel is closed) should be made via this 
handle. 


Possible errors from the p_open call include: 


e "invalid arguments" - which probably means sndfrc.ldd has not been installed (or, having once 
been installed, it has since been de-installed) 


e "in use" or "locked" - another application is currently making use of the loudspeaker. 


In the second of these two cases, a brief retry philosophy might be adopted. If the channel still cannot be 
opened, a suitable error message should be displayed - leaving it up to the user to retry at some later time. 


Actually creating sounds 


The way sounds are actually caused to be emitted is by using the P_FwRITE service of the mus: channel. 


As for all device drivers, the P_FWRITE request can be made synchronously (eg using the utility function 
p_write) or, for more quality applications, asynchronously. If the request is made asynchronously, it 
allows the use of the P_FCANCEL service to interrupt and terminate a sequence of notes as they are playing. 


For example, 
p_ioc5 (handle, P_FWRITE, &musstat, &buf[0],é&len); 
to play a buffer of notes asynchronously. 


The parameter len (passed by reference) gives the number of notes in the buffer. The maximum allowed 
value of 1en is 500. (For arbitrarily long sequences of notes, call the Pp_FwRITE service more than once.) 


Each note is specified by one uworp in the buffer - so that but would be declared as 
UWORD buf[ ] 
For each note, the uworp contains three pieces of information: tone, length, and loudness. 


There are only four possible values of loudness: 0 (the quietest), 1, 2, and 3 (the loudest). The loudness is 
multiplied by 64 before being added into the uworp for the note. 


The duration is measured in 1/100ths of a second, and can have any value from 1 to 255. The duration is 
multiplied by 256 before being added into the uworp for the note. 


The allowed values of tone range in principle from 0 to 0x3£. See below for more details. 


3 ENHANCED SOUND OUTPUT 


Example 


#include <p_std.h> 
#include <p_file.h> 
#include <epoc.h> 


GLDEF_C INT main(VOID) 
{ 
INT ret; 
VOID *mcb; 
UWORD buf[10]; 
UWORD len; 
WORD musstat; 


ret=p_loadldd("SNDFRC.LDD") ; 
if (ret && ret!=E_FILE_EXIST) 
return (ret); 
ret=p_open (&mcb, "MUS:",-1); 
if (ret) 
return (ret); 
=0x30+ (40<<8) ; 
=0x32+ (100<<8) ; 
buf =0x34+ (40<<8) + (1<<6); 


buf [0 
i 
2 
buf [3] =0x35+ (100<<8) + (1<<6); 
4 
5 
6 


buf 


buf =0x37+ (40<<8) + (2<<6); 

=0x39+ (100<<8) + (2<<6) ; 

buf =0x29+ (40<<8) + (3<<6); 

buf [7] =0x3b+ (100<<8) + (3<<6); 

len=8; 

p_ioa5 (mcb, P_FWRITE, &musstat, &ébuf[0],é&len); 
p_iowait (); 

return (0); 


} 


buf 


This plays a scale of eight notes, with notes having wavering length and increasing loudness. 


Possible tones 


There are three types of tones that the Series 3 loudspeaker hardware can emit: DTMF tones, modem 
tones, and musical tones. 


For standard dual DTMF tones, set the tone part of the uworp to: 0x10 for DTMF digit 0, 0x11 for digit 1, 
..., 0x19 for digit 9, ox1a for "digit" a, ..., 0x1d for "digit" 4d, ox1e for *, and ox1¢ for #. 


For modem tones, 0x24 gives 1300 Hz, 0x25 gives 2100 Hz, then 1200, 2200, 980, 1180, 1070, 1270, 1650, 
1850, 2025, and 0x2f gives 2225 Hz. 


As for musical tones, twenty five notes are possible, incrementing by semi-tones over a 2-octave interval 
from p#5 to p#7. The corresponding tone values are 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 
0x39, 0x3a, 0x29, 0x3b, 0x3c, 0x3d, 0x0e, 0x3e, 0x2c, 0x3f, 0x04, 0x05, 0x25, Ox2£, 0x06, and 0x07. 


Pauses 
In order to pause, in the middle of a buffer of notes, set the tone value to o for one note. 
When to open and close MUS: 


An application that makes use of mus: services from time to time ought to call p_close to free the sound 
channel whenever it is not immediately needed. This allows other applications to make temporary use of 
the sound channel - eg for alarms or for standard DTMF dialling dialogs. 


If you wrote a game which opened mus: at its beginning, and only made sounds from time to time, and left 
this game in background while you went to the Data application to look up a telephone number, you 
would find the DTMF dialler would be unable to emit any sounds, and would report "Sound system in 
use" - even though the game is silent at the time. 


Far better in these situations for a program to open mus: just before it needs to use this channel, and then 
close it again immediately afterwards. 


3-3 


SERIES 3/3A PROGRAMMING GUIDE 


When to install and de-install the Idd file 


Once sndfrc.ldd has been installed, it occupies about 1.7 K of RAM. For this reason, it would seem to be 
best to de-install it, when the application terminates. The way to do this is to call (see the Plib Reference 
manual for more details) 


p_devdel ("MUS:",E_LDD) ; 


This call will fail if another application currently has an open channel to mus:. Applications should ignore 
any errors from p_devdel. 


Note however that if an application has: 
e ~=called p_loadidd to ensure mus: can be found 
e called p_open to open a channel to mus: 
e played some notes 
e called p_close to free up the sound channel 


then it cannot rely on mus: still being installed if it calls p_open again at a later stage. For another 
application may have called p_devde1, successfully, in the meantime. 


The upshot of this is that applications should call p_1oadidd prior to any call to open a channel to mus:. 


Sound on the Series 3a 


This section does not make reference to the recording and playing of digital sound - for details see the 
General System Services chapter of the Plib Reference manual. 


The Series 3a's built-in snp: device driver can be used to simultaneously play two tunes on the built-in 
speaker. Although the sound quality is not as high as with digital sound files, the memory requirements 
are much less. For example to play a tune lasting six seconds would require a digital sound file of size 
49,184 bytes. A comparable figure using the snp: device driver would be less than 1 Kb. 


The demonstration program sound.c (in \SIBOSDK\DEMO on the supplied disks) plays two sequences of 
notes using both channels of the built-in snp: sound device driver (only one application can have access to 
these channels at any given time). The tune is the so-called "ice cream van" tune that you may already 
have met in the Sound chapter of the i/o Devices manual - it is in any case recommended that you read 
that chapter before proceeding. 


The program demonstrates the following: 
e the opening and closing of a channel to the snp: device driver. 
e the sensing and setting of the volume level and the number of beats per minute. 
e the writing of notes to the two sound channels. 

A number of points are worth making: 


e aside effect of opening a channel to the snp: device driver is to power up the speaker. As a 
consequence the snp: channel should be closed as soon as the sound has been played - failure to 
do so could unnecessarily drain the batteries. 


e the snp: device driver, and hence the speaker, can only be used by one application at a time. As 
alarms and keyclicks will be disabled well written programs should close the snp: channel as 
soon as the sound has been played. 


e a serious of notes separated by silences can be created by setting the frequency to zero during the 
silent periods. 


e the sound will not play until a p_rFsSoUNDCHANNELn request has been made on both channels. The 
playing of sound on the two channels is thus automatically synchronised. 


e both p_FSSOUNDCHANNELn requests must be made asynchronously using p_ioc or the p_ioc5 
variant. On a low battery the request will fail to complete with an error message written to the 
status word. Use of p_iow, p_iow4, p_ioa and/or p_ioa5 would hang the machine on a low 
battery - a very serious programming error. 


3-4 


3 ENHANCED SOUND OUTPUT 


e sound can be played on only one channel by passing the other channel a length of zero for the 
note buffer - i.e. zero notes. 


e the P_FSET service sets both the volume and the beats per minute. The P_FSENSE service can 
be requested first to ensure that one or other parameter remains unchanged. 


To create a sound.img file simply type make sound in the appropriate directory. This file can then be 
copied to a m:\img directory on the Series 3a and run via the RunImg application in the usual manner. 


The code in sound.c is as follows: 


#include <p_std.h> 
#include <p_file.h> 
#include <epoc.h> 


GLDEF_C VOID waitstat2(WORD *pstatl, WORD *pstat2) 


/* Wait for *pstat!=E_FILE_PENDING and *pstat2 != E_FILE_PENDING */ 


INT i; 


i= -1; 


{ 


p_iowait (); 


Fa 

} 

while (*pstatl == E_FILE_PENDING && *pstat2 == E_FILE_PENDING) ; 
if (*pstat2 == E_FILE_PENDING) 


pstatl = pstat2; 
p_waitstat (pstat1); 


while (i--) 
p_iosignal(); 
} 


GLDEF_C VOID play_notes(WORD *bufl, WORD *buf2, WORD 11, WORD 12, INT volume, INT 
beatsPerMinute) 


{ 

VOID *pcb; 

WORD sndstat1l,sndstat2; 
E_SOUND sound; 

INT err; 


if ((err=p_open (&pcb, "SND:",-1) ) <0) 
{ 
p_close (pcb); 
p_exit (err); 


} 


if ((err=p_iow3 (pcb, P_FSENSE, &sound) ) <0) 
{ 
p_close (pcb); 
p_exit (err); 


} 


if (beatsPerMinute >= 0) 
sound.beatsPerMinute = (UBYTE) beatsPerMinute; 


if (volume >= 0) 
sound.volume = (UBYTE) volume; 


if ((err=p_iow3 (pcb, P_FSET, &sound) ) <0) 
{ 
p_close (pcb); 
p_exit (err); 


} 


3-5 


SERIES 3/3A PROGRAMMING GUIDE 


p_ioc5 (pcb, E_FSSOUNDCHANNEL1, &ésndstat1, &buf1[0],&11); 
p_ioc5 (pcb, E_FSSOUNDCHANNEL2, &ésndstat2, &buf2[0],&12); 
waitstat2 (&sndstat1l, &ésndstat2) ; 


p_close (pcb); 


if (sndstat1 != 0 || sndstat1 != 0) 
p_exit (0)); 


} 
GLDEF_C INT main(VOID) 


{ 


WORD notes1[] = {1048,24,524,12}; 
WORD notes2[] = {1048,4,1320,4,1568,4,2092,4,1568,4,1320,4,1048,12}; 
WORD lenl = sizeof (notes1)/4,len2 = sizeof (notes2) /4; 

INT i; 

for (i = 0; i < 6; i++) 


{ 

play_notes (&notes1[0],&énotes2[0],len1l,len2,i,-1) 
p_sleep (1); 

} 


for (i = 0; i < 6; i++) 
{ 
play_notes (&notes1[0],&énotes2[0],lenl,len2,-1,140 + i*20) 
p_sleep (1); 
} 
return (0); 


} 


The main routine initialises the note buffers, then repeatedly passes the buffers, the buffer lengths, the 
volume and the beats per minute, to the subroutine play_sound that plays the tune. The tune is repeated 
first at the default beats per minute for all six allowed volume levels, and then at the default volume for 
six values of the beats per minute. The default is specified by passing a negative integer for the volume 
and/or the beats per minute. 


The subroutine play_sound opens the snp: channel, senses and sets the volume and beats per minute, 
plays the notes and closes the snp: channel. In the case of an error in, for example, sensing, play_sound 
closes the snp: channel and returns with an error code. As mentioned earlier it is essential that the 
P_FSSOUNDCHANNELn requests be made asynchronously using either p_ioc or p_iocs5 Plib library routines, 
as these guarantee completion even in the event of low batteries. 


A large fraction of the code in play_sound is concerned with error checking in order to ensure that the 
routine behaves in a sociable way. In particular the snp: channel is closed as soon as an error is 
discovered so to conserve power - this is essential when running on batteries and such measures should be 
standard in any quality application. 


The subroutine waitstat waits on the process i/o semaphore until completion of the two asynchronous 
requests specified by the pstat1 and pstat2 status words (for further details of such matters see the 
Asynchronous Requests and Semaphores chapter of the Plib Reference library). It is in fact a version of 
the Plib library routine p_waitstat that waits on two status words rather than one. 


The return (0) statement at the end of the main routine informs the Series 3a that the program has ended 
normally: it can also be omitted entirely. Use of the return statement with no return value is not 
recommended: in practice this will return a random error code possibly leading to the display of a 
spurious full screen error message. 


3-6 


CHAPTER 4 


USE OF SPY.APP 


Introduction 


This chapter describes the Spy application for the Series 3. This application contains many features that 
may help to "debug" problems with applications on the Series 3. 


The version of Spy described in this chapter is suitable for use on both the Series 3 and the Workabout, 
and can also be used on the Series 3a. A built version of spy.app that is specifically designed for use on 
the Series 3a will be found, following installation of the core SDK software, in the \sibosdk\s3atool 
directory. 


Building spy.app 

The Spy application is released in source form, as one of the Hwif demonstration programs. 

To build it, proceed in the same way as to build any of the other Hwif demonstration programs: 
e¢ move into the \sibosdk\hwdemo directory 
e type make spy 


e the resulting image file spy.img can be renamed to spy.app and copied into a \app directory on 
the Series 3 or the Workabout 


e the application can be installed in the System Screen and, on the Series 3, even assigned an 
application button - eg CONTROL+WORLD. 


The main display 


The main display is a scrolling list of processes currently running on the Series 3. The Change processes 
menu option allows customisation of which processes are shown. "System" processes are simply ones 
whose names start with "Sys$", and include: 


e — sys$shil - which the user sees as the System Screen 
¢ —sys$wsrv - the Window Server, which coordinates access to the screen and keyboard 
e — sys$fsrv - the File Server, which coordinates access to the filing systems 


e —sys$mang - the Manager, which keeps track of all resources used by processes (so that, for 
example, they can be properly tidied whenever processes exit) 


e — sys$ncp - the "brains" behind Remote Link (when it is running). 


The Null process, sys$null, which performs the vital task of switching the Series 3 off following sufficient 
inactivity, is omitted from the list displayed, for various technical reasons. 


First letter matching works in the main window, so that eg pressing 'C' enough times will position the 
highlight to the Calc process. 


Arrows are drawn in the top right and bottom right corner, Agenda-wise, whenever there are more 
processes beyond the visible boundaries of the list. 


SERIES 3/3A PROGRAMMING GUIDE 


The data displayed is updated every time Spy comes into foreground, and also whenever the Update menu 
option is selected. By default, it is also updated regularly on a timer, though this can be disabled by a 
menu option. The Refresh rate option governs how frequently updates take place, when the timer is 
enabled. 


There are in all twelve pieces of data that can be displayed for each process, but only three of these can be 
seen at any one time. Use the Change data menu option to choose which. 


Many of the data items can be meaningfully displayed either in Hex or in Decimal. Another menu option 
controls this. 


Heap statistics 


Five of the twelve possible items of data concern the allocator heap of the process. Each process has its 
own heap, which can vary in size according to the needs of the program. Thus a Word Processor editing a 
large document will typically have a larger heap than a Word Processor editing a smaller document. 


Each heap is divided into "alloced cells" and "free cells". The items "Cells allocated" and "Cells free" 
count these, and the items "Bytes allocated" and "Bytes free" sum how many bytes belong in each 
category. 


This data can be of great help in developing applications. It is of course vital that an application frees 
cells it no longer requires - otherwise these cells go to what is called "alloc heaven". Something to watch 
for in particular is alloc heaven following an out-of-memory failure. Typically, a process such as 
launching a dialog involves a number of different allocs; if any one of these fails, all the allocs which have 
already succeeded must be undone. System code provides mechanisms such as "automatic destruction" 
and "automated clean-up" to help applications here, but applications can use these incorrectly at times - 
hence the need for real-time checking. 


Stack statistics 


Whenever a process starts, its stack is filled up with oxrr's. This makes it easy to see how much stack has 
been used, at any one time. Quality programs need to avoid having too large a stack - the built-in 
applications default to a stack of 0xa00. On the other hand, the operating system panics them (panic 69) 
if it ever discovers that their stack is less than 0x100. This is because whenever an interrupt occurs, it 
runs in the stack of the current process. 


The Reset least stack menu option simply refills the bottom of the process's stack with oxFF's (ie up to its 
present stack pointer). 


Segment statistics 


The "Segment size" of a process gives the size of its data segment - which consists of the heap, static data 
private to the application, the stack, and finally the Epoc reserved statics at the bottom end. The quoted 
"Segment size" of an application can sometimes give a misleading account of how much memory it is 
actually using - since there are free cells as well as alloced cells in the heap. From time to time, the 
operating system may try to compress these heaps, but it can only do this by removing any free cells at the 
end of the heap. Applications should strive to avoid ending up with large free cells in the middle of their 
heap - though this is a very difficult goal to achieve. 


Tests for heap integrity 


Whenever Spy collects heap statistics for an application, it also checks the heap integrity. Any defect 
(caused for example by writing beyond the end of an alloc cell, or freeing a cell that was never alloced) 
results in an immediate alert. This alert helps to pin-point problems which would otherwise only rear 
their head much later - long after the real damage has been done. 


Process priorities 


The Process Priority gives the pecking order of the processes, as regards gaining CPU from the multi- 
tasking scheduler. Most applications the user sees run at 0x80 when in foreground, and at 0x70 when in 
background. This prevents computationally busy background tasks from detracting from the performance 
of the foreground task. 


Spy momentarily ups its own priority to a massive 0xc0 (the maximum allowed to non-OS processes) 
whenever it collects heap statistics from other processes, to lessen the chances of other processes 
manipulating their heaps at the same time as Spy is walking through them. Occasionally, Spy will find 
that a heap is momentarily marked as "locked" when it tries to survey it - this indicating that the 
Operating System is busy doing something there - in which case the heap statistics will all just be shown 
as 0 for that process. 


4 USE OF SPY.APP 


Other data 


The "Process ID" of a process is essentially the address of the control block of the application in the 
Operating System data space, although the top nibble reflects how many times that same slot has been re- 
used since the last reset (the top nibble will therefore always be zero for sys$mang, sys$fsrv, and 
sys$wsrv). When processes talk to each other, for example in conjunction with the Bring menu option, 
they need to know each other's PID ("Process ID"). 


The IO Semaphore count basically keeps track of how many outstanding events a process has to respond 
to. This will usually be -1 or zero, but if you task to the System Screen and then straight back to Spy 
again, you may see the count for sys$shll momentarily go as high as three. 


Logging Window Server statistics 


The menu command Log client produces information in text file form as to the structure of the windows, 
GCs, fonts, bitmaps, and other Window Server objects "owned" by an application. This information may 
of use in determining why certain drawing fails to appear on the screen. For example, it may be that a 
window is positioned wrongly, that the window is obscured by another, or that the current GC is set up 
incorrectly - any such failure can be seen from the log file. 


The menu command Log all clients repeats this process for all the clients of the Window Server. 


The Log client command can, in effect, be invoked even when Spy is in background. Just press the key 
combination SHIFT+CONTROL+PSION+N and a dump of the Window Server object usage of the foreground 
application will be created - by default in the file \oepAwsreport.lis. (This feature works because Spy has 
"captured" this key combination.) 


APPENDIX A 


TECHNICAL SPECIFICATIONS 


Psion's continuing product development and improvement programs mean that specifications and features 
are subject to change at any time and without notice. 


Psion Series 3a Technical Specification 


Physical characteristics 


Part numbers: 


Size 
Weight 


Screen 


Keyboard 


Sound and recording 


Power supply 
Internal 
Backup 


External 


Memory 


Built in 


System information 
Processor 


Operating system 


1600-0029-10 (256KB) 
1600-0025-10 (512KB) 
1600-0080-10 (1MB) 
1600-0082-10 (2MB) 


165mm x 85mm x 22mm (6.5"x 3.0"x 0.9"). 
275g (including batteries). 


480 x 160 pixel high contrast retardation film LCD. 
Size 131.6mm x 45.2mm, (4.915" x 1.637"). 

Pixel pitch 0.26mm x 0.26mm 

Pixel size 0.23mm x 0.23mm. 


58 key, QWERTY layout, computer style keyboard (UK models). 
8 touch sensitive icon buttons for application selection. 


Loudspeaker with DTMF dialling and digital sound playback. 
Microphone for digital sound recording. 


2 x AA batteries. 
3V Lithium CR1620 battery. 


A Psion Series 3 mains adaptor, (9-11V 250mA), (Note: earlier models 175mA). 
Vehicle power adaptor (24v & 12v cigarette lighter sockets), from Jan/Feb 1997. 


2MB or IMB Masked ROM and 2MB, 1MB, 512KB or 256KB RAM. 
Two SSD drives allow extra storage space on Flash/RAM SSDs, up to 8MB. 


NEC V30H running at 7.68MHz. 


EPOC. 
Microsoft MS-DOS compatible Flash Filing System. 


SERIES 3/3A PROGRAMMING GUIDE 


Expansion 


Peripherals 


Socket: 


Environment 


Operating temperatures 
EMC 


External peripherals (such as a modems and printers) can be connected via a 
fast serial interface (1.536 Mbits/sec), which accepts optional 3Link parallel 
and serial interfaces. The Serial 3Link allows communication with other 
computers. 


PC Card adapter. SMS cables for Nokia and Orange mobile phones. 
3Fax fax modem, (superseded by PC Card adapter). 


6-way two row rectangular (male, with retracting protective cover). 
See the section ‘The 15-way SIBO/RS232 connector’ in the 'SIBO Expansion 
Ports' chapter in the Hardware Reference manual for pinout details. 


O°C to 50°C. 
FCC Part 15 Class B; CE Mark 


Psion Series 3/3s Technical Specification 


These models are no longer in production. 


Physical characteristics 


Size 
Weight 


Screen 


Keyboard 


Sound 


Power supply 
Internal 
Backup 


External 


Memory 
Built in 


System information 
Processor 


Operating system 


165mm x 85mm x 22mm (6.5"x 3.0"x 0.9"). 
265g (including batteries). 


240 x 80 pixel high contrast retardation film LCD. 
Size 97.3mm x 38.9mm. 

Pixel pitch 0.385mm x 0.43mm 

Pixel size 0.355mm x 0.4mm. 


58 key, QWERTY layout, computer style keyboard (UK models). 
8 touch sensitive icon buttons for application selection. 


Piezo buzzer. 
Loudspeaker with DTMF dialing. 


2 x AA batteries. 
3V Lithium CR1620 battery. 


A Psion Series 3 mains adaptor, (9-11V 250mA), (Note: earlier models 
175mA). 

Vehicle power adaptor (24v & 12v cigarette lighter sockets), from Jan/Feb 
1997. 


Series 3 has 384KB or 512KB Masked ROM and 128KB or 256KB RAM, 
Series 3s has 512KB Masked ROM and 256KB RAM. 


Two SSD drives allow extra storage space on Flash/RAM SSDs, up to 8MB. 


NEC V30H running at 3.84MHz. 


EPOC. 
Microsoft MS-DOS compatible Flash Filing System. 


Expansion 


Peripherals 


Socket: 


Environment 


Operating temperatures: 


EMC: 


APPENDIX A: TECHNICAL SPECIFICATIONS 


External peripherals (such as a modems and printers) can be connected via 
the fast serial interface (1.536 Mbits/sec), which accepts optional 3Link 
parallel and serial interfaces. The Serial 3Link allows communication with 
other computers. 


6-way two row rectangular (male, with retracting protective cover). 
See the "Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


O°C to 50°C. 
FCC Class B; EN55022 Class B 


Psion Series 3c Technical Specification 


Physical characteristics 


Part numbers: 


Size 
Weight 


Screen 


Keyboard 


Sound and recording 


Power supply 
Internal 
Backup 


External 


Memory 
Built in 


System information 
Processor 


Operating system 


Communications 
Infrared: 


Protocols: 


Language 


1600-0126-10 (IMB) 
1600-0122-10 (2MB) 


165mm x 85mm x 22mm (6.5"x 3.0"x 0.9"). 
275g (including batteries). 


480 x 160 pixel high contrast retardation film LCD. 
Size 131.6mm x 45.2mm, (4.915" x 1.637"). 

Pixel pitch 0.26mm x 0.26mm 

Pixel size 0.23mm x 0.23mm. 


58 key, QWERTY layout, computer style keyboard (UK models). 
9 touch sensitive icon buttons for application selection. 


Loudspeaker with DTMF dialing and digital sound playback. 
Microphone for digital sound recording. 


2 x AA batteries. 
3V Lithium CR1620 battery. 


A Psion Series 3 mains adaptor, (9-11V 250mA), (Note: earlier models 
175mA). 

Vehicle power adaptor (24v & 12v cigarette lighter sockets), from Jan/Feb 
1997. 


2MB Masked ROM and IMB or 2MB RAM. 
Two SSD drives allow extra storage space on Flash/RAM SSDs, up to 8MB. 


NEC V30H running at 7.68MHz. 


EPOC. 
Microsoft MS-DOS compatible Flash Filing System. 


IrDA SIR optical link, for IR communications and printing. 


XMODEM, YMODEM and ZMODEM, (except from Comms Script in early 
models), giving compatibility with most computer communications software. 


Full script language with sample scripts allows automated log-on to 
electronic mail and other systems, and control of modems. 


SERIES 3/3A PROGRAMMING GUIDE 


Expansion 


Peripherals 


Socket: 


Environment 


Operating temperatures: 


EMC: 
Safety: 


External peripherals (such as a modems and printers) can be connected via 
the RS232 port which accepts optional PC Link and Parallel Printer Link 


cables. The PC Link allows communication with other computers. 


Travel Modem. PC Card adapter. SMS cables for Ericsson, Nokia and 


Orange mobile phones. 


15-way Honda type custom connector 


See the section ‘The 15-way SIBO/RS232 connector' in the 'SIBO Expansion 


Ports’ chapter in the Hardware Reference manual for pinout details. 


O°C to 50°C. 
FCC Part 15 Class B; CE Mark 
EN60950 


Psion Siena Technical Specification 


Physical characteristics 


Part numbers: 


Size 
Weight 


Screen 


Keyboard 


Sound 


Power supply 


Internal 


Backup 


External 


Memory 
Built in 


System information 


Processor 


Operating system 


1010-0003-01 (1MB) 
1010-0002-01 (512KB) 


150mm x 70mm x 18mm (5.9"x 2.7"x 0.7"). 
180g (including batteries). 


240 x 160 pixel high contrast retardation film LCD. 
Size 60.0mm x 40.0mm, (2.36" x 1.57"). 

Pixel pitch 0.25mm x 0.25mm 

Pixel size 0.23mm x 0.23mm. 


48 key, QWERTY layout, computer style keyboard (UK models). 
20 key calculator keypad 
8 touch sensitive icon buttons for application selection. 


Piezo buzzer. 


2 x AAA batteries 
giving approximately 40hrs use (2 months typical usage). 


3V Lithium CR1620 battery. 


From a Siena SSD Drive 


1MB Masked ROM and 512KB or 1MB RAM. 


NEC V30H running at 7.68MHz. 


EPOC. 
Microsoft MS-DOS compatible Flash Filing System. 


Communications 


Infrared: 


Expansion 


Peripherals 


Socket: 


Environment 


Operating temperatures: 
EMC: 
Safety: 


APPENDIX A: TECHNICAL SPECIFICATIONS 


IrDA SIR optical link, for IR communications and printing. 

The Siena does not have the DYL file in ROM to support the AccessIr API 
(for Infrared beaming), this is provided with this SDK and must be loaded 
before third party programs using this API can be used. 

The Siena does not have the DYL file in ROM to support the IrLPT API (for 
Infrared printing), this must be loaded before third party programs using this 
API can be used. 


External peripherals (such as a modems and printers) can be connected via 
the RS232 port which accepts optional PC Link and Parallel Printer Link 
cables. The PC Link allows communication with other computers. 


External SSD Drive, via 1.536Mbits/sec Fast Serial interface. 


PC Card adapter. SMS cables for Ericsson, Nokia and Orange mobile 
phones. 


15-way Honda type custom connector 
See the "Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


O°C to 50°C. 
FCC Part 15 Class B; CE Mark 
EN60950 


Psion Siena SSD Drive Technical Specification 


Physical characteristics 


Part number: 
Compatibility: 
EMC: 

Safety: 

Size 

Weight 

Power input: 
Power output: 


Connectors: 


SSD slots: 


1011-0005-01 

Psion Siena only 

FCC Part 15 Class B; CE Mark 

EN60950 

118mm x 69mm x 15mm (4.62"x 2.7"x 0.6"), (pre-production model). 

87g, including flying lead, (pre-production model). 

A Psion Series 3c mains adaptor, (9-11V 250mA), (supplied with the drive). 
Power is supplied to a connected Siena via the RS232 connector. 


15-way Honda type custom plug on flying lead to connect to the Siena 
15-way Honda type custom socket to connect to a PC (for use with PsiWin) 


One SSD slot; accepts all capacities of Flash/RAM SSD. 


Psion Serial 3Link Technical Specification 


The Serial 3Link comes in two versions, one for IBM PC compatible computers and the other for Apple 


Macintosh machines. 


Part number (PC): 


Part number (Apple): 
Compatibility: 


EMC 


1601-0001-01 (cable only) 
1601-0039-11 (with PsiWin software) 
1601-0002-10 (with V1.41 software) 


Series 3, Series 3a 
(The Psion Series 3c and Psion Siena machines use a different type of 
communications cable, the PC Link cable.) 


FCC Part 15 Class B; CE Mark 


SERIES 3/3A PROGRAMMING GUIDE 


Safety: 
Physical 


Interface 


Memory 
Protocols 
Language 


Communications 
software 


Connectors - IBM PC 


Connector - Apple Mac 


Connectors 
- both versions 


EN60950 


Pod with lead for connection to the Series 3 or LIF adaptor. 

Pod incorporates "auto wake up" switch. 

Replaceable lead to connect the pod to the other computer or peripheral. 
Complete connection is functionally equivalent to a 'null modem’ cable. 


RS232. 


Masked ROM in the 3Link pod. This contains the script language and 
supporting communications software. The pod appears as SSD drive C. 


XMODEM and YMODEM, giving compatibility with most computer 
communications software. 


Full script language with sample scripts allows automated log-on to 
electronic mail and other systems, and control of modems. 


Link and/or RCom and/or PsiWin software supplied provides a simple 
interface for exchanging information with IBM PC compatibles and with the 
Apple Macintosh, giving direct remote file access. 


9-pin D-type (for connection to an IBM AT type PC or modem serial 
port). 

25-pin D-type (for connection to an IBM XT type PC or modem serial port. 
Note: The model currently distributed through retail channels only has a 
9-pin D-type connector, but the Serial 3Link assembly is available as 
separate cables and pod - see below). 


Pin name Description Pin number Direction 
PC - 3Link 

FG Frame Ground 1 — 
(earth) 

TD Transmitted Data 2 > 

RD Received Data 3 - 

RTS Request To Send 4 > 

CTS Clear To Send 5 ce 

DSR Data Set Ready 6 eS 

SG Signal Ground 7 — 
(common return) 

DTR Data Terminal Ready 20 > 

8-pin round 


6-way two row rectangular (female) plug 

for connection to the Series 3 serial port, or Psion LIF adaptor (Workabout). 
See the "Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


9-pin round (Internal connector on the 3Link pod) 
Pin name Description Pin number Direction 
Series 3 - Other 
DCD Data Carrier Detect 1 ce 
RD Received Data 2 a 
TD Transmitted Data 3 > 
DTR Data terminal Ready 4 > 
SG Signal Ground 5 > 
(common return) 
DSR Data Set Ready 6 ce 
RTS Request To Send 7 > 
CTS Clear To Send 8 a 
RI Ring Indicator 9 - 


See below for diagram of pinout. 


APPENDIX A: TECHNICAL SPECIFICATIONS 


See the Psion Series 3 3Link (RS232) manual provided with the 3Link for full details of operation. 


PC Serial 3Link assembly components 


The PC Serial 3Link assembly is available as separate components with the following part numbers: 


RS232 Cable 3Link Pod and cable to Psion 2500 0005 10 
9 Pin Cable to PC 2303 0004 02 
25 Pin Cable to PC 1404 0003 

Double headed Cable to PC 2303 0016 02 


PC Serial 3Link to Apple Macintosh converter 


This converter changes a PC Serial 3Link into an Apple Macintosh Serial 3Link: 
2 x disks, 1 x cable, 1 x manual 1601 0019 O01 


Modem Adaptor cable 


This converter changes a Series 3a PC/Mac Serial 3Link cable so that the Psion can be connected to a 
Hayes compatible modem: 


Series 3a Serial 3Link Modem Adaptor cable 1404 0002 


Serial Printer cable (Series 3a) 
- Technical Specification 


Part number: 1404 0001 

Compatibility: Psion Series 3/3s and Psion Series 3a only. 
EMC: FCC Part 15 Class B; CE Mark 

Safety: EN60950 

Connectors: 6-way two row rectangular (female) plug 


for connection to the Series 3/3s/3a serial port. 
See the "Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


RS-232 25 way D-type connector (male). 


SERIES 3/3A PROGRAMMING GUIDE 


Serial Printer cable (Series 3c/Siena) 
- Technical Specification 


Part number: 1602-0017-01 

Compatibility: Psion Series 3c and Psion Siena only. 
EMC: FCC Part 15 Class B; CE Mark 

Safety: EN60950 

Connectors: Low Profile Honda type custom connector 


RS-232 25 way D-type connector (male) 


Psion PC Link cable Technical Specification 


The Psion Series 3c and Psion Siena machines use this new type of communications cable. 


Part number: 2013-0002-01 (cable only - available to developers by special request) 
1011-0010-01 (with PsiWin software) 
Compatibility: Psion Series 3c and Psion Siena only. 


To connect to other devices with 25 way D-type connectors, adapters are 
needed, (see Psion 9-to-25 way D-type adapters Technical Specification) 


EMC: FCC Part 15 Class B; CE Mark 
Safety: EN60950 
Connectors: Low Profile Honda type custom connector 


RS-232 9 way D-type connector (IBM AT type) 


Modem Adaptor cable 


This converter changes a Series 3c/Siena PC/Mac Link cable so that the Psion can be connected to a 
Hayes compatible modem: 


Series 3c Serial Link Modem Adaptor cable 1602 0016 01 


Psion Mac Link cable Technical Specification 


The Psion Series 3c and Psion Siena machines use this new type of communications cable. 


Part number: 1601-0101-01 

Compatibility: Psion Series 3c and Psion Siena only. 
EMC: FCC Part 15 Class B; CE Mark 

Safety: EN60950 

Connectors: Low Profile Honda type custom connector 


RS-232 (Apple connector) 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Psion 9-to-25 way D-type adapters 
- Technical Specification 


The Psion series 3c and Psion Siena machines use a different type of communications cable from 
preceding machines;- the Psion PC Link cable. To connect to other 25 way D-type connector devices, 
adapters are needed as, unlike the 3Link cable, this is a single cable and can’t be split to change the RS- 
232 half to connect to a serial printer or modem. 


The new PC Link and 3Link cables use the pins on the D-type plugs in a unique way. This means that a 
unique mapping from 9-to-25 way pinouts is required, so special adapters (i.e. non-industry standard) 
have been designed to provide this unique mapping. 


Except in special cases, these adapters replace the need for the old RS-232 serial printer and modem 
cables for 3Link users. In addition, these adapters allow connection of a 3Link or PC Link cable to a PC 
with 25 way communication ports. 


The three types of Psion branded RS232 9-to-25 way D-type adapters allow any Psion cable with a 9 way 
D-type connector to be connected to another machine with a IBM XT type PC 25 way D-type port or 
modem or printer serial port. 


Adapter Part number EMC Safety 

Modem 1602 0016 01 FCC Part 15 Class B; CE Mark EN60950 
Serial Printer 1602 0017 O1 FCC Part 15 Class B; CE Mark EN60950 
PC (XT) 1602 0015 01 FCC Part 15 Class B; CE Mark EN60950 


Modem 9-to-25 way D-type adapter - wiring diagram 


9 way D - male 25 way D - male 
RX - pin 3 
TX - pin 2 
DTR - pin 6 


[RX - pin3 | 
| TX -pin2 | 
| DTR- pin6 | 
GND - pin 5 
| _DSR- pin 4 | 
| RTS - pin8 | 
| CTS - pin7 | 
| DCD - ping | 


DSR - pin 4 
RTS - pin 8 
CTS - pin 7 
DCD - pin 9 


SHELL 


PC (XT) 9-to-25 way D-type adapter - wiring diagram 


9 way D - male 25 way D - female 
| RX - pin 3 Fj pin-2 
| TX pin 2 >} F pin 3 
| _DTR- pin 6 -}—__—jpin-6_ 
| GND - pin 5 | pin-7 
| __DSR-pin 4 |§—____pin- 20 
| __ RTS - pin 8 -}——jpin-5 
| _CTS - pin? |} F pin-4 
| DCD - pin 9 |F—____—j pin-7 
(ton te 


SERIES 3/3A PROGRAMMING GUIDE 


Printer 9-to-25 way D-type adapter - wiring diagram 


9 way D - male 25 way D - male 
| WRX - pin 3 Fj pin-2 
| TX pin 2 | F pin-3 
| _DTR-pin 6 |} pin-6_ 
| GND - pin 5 | pin-7 
| __DSR- pin 4 -——____j pin-20_ 
| _RTS - pin 8 Fj pin -5,8 
| __ CTS - pin 7 |} pin-4 
| DCD -pin 9 |} pin-7 
int 


Psion Parallel 3Link Technical Specification 


Part number: 


Compatibility: 


EMC: 


Interface: 


Connectors: 


1601-0003-10 


Psion Series 3, Psion Series 3 and Psion Workabout with LIF adaptor only 
(The Psion Series 3c and Psion Siena machines use a different type of printer 
cable, the Parallel Printer Link cable. ) 


FCC Part 15 Class B; CE Mark 


Centronics interface for parallel printers 


6-way two row rectangular (female) custom plug, for connection to the 
Series 3 or Series 3a serial port, or Psion LIF adaptor (Workabout). 

See the "Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


Centronics (for connection to the parallel port of a printer) 


Psion Parallel Printer Link cable 
- Technical Specification 


Part number: 


Compatibility: 


EMC: 
Safety: 


Connectors: 


Power: 


A-10 


1011-0017-01 


Psion Series 3c and Psion Siena only 

The Parallel Printer Link is not for use with the Series 3, Series 3a, MC, HC 
or Workabout, (The Psion Series 3 and Psion Series 3a machines use a 
different type of printer cable, the Psion Parallel 3Link cable.) 


FCC Part 15 Class B; CE Mark 
EN60950 
Low Profile Honda type custom connector 


Centronics connector (to connect to a Centronics type parallel printer port) 


One 9V PP3 battery. 
With typical usage, the expected life from a new battery is 150 hours. 
Power is only consumed when printing. 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Psion PC Card Modem Adapter 
- Technical Specification 


Variants 


There are three variants: 


e = Series 3a 
e = Series 3c 


e PC 


The PC Card Modem Adapter with a suitable PC Card modem, combined with the PsiFax software, 
supersedes the 3Fax modem and software for the Series 3a. For the Series 3c there is also the alternative 


Travel Modem. 


Physical characteristics 


Part number: 


Compatibility: 


EMC: 
Safety: 
Size 
Weight 


Processor: 
Memory: 


Power: 


Battery life: 


Interface to computer: 


User interface: 


Connectors: 


Series 3a variant: 2501-0223-01 (unboxed, not retail) 
Series 3c variant: 2501-0224-01 (unboxed, not retail) 
PC variant: 2501-0225-01 (unboxed, not retail) 


Psion Series 3a - Series 3a variant only 

Psion HC - Series 3a variant only, with LIF connector module & LIF adapter 
Psion Workabout - Series 3a variant only, with LIF adapter 

Psion Series 3c - Series 3c variant only 

PC - PC variant only 


The PC Card Modem Adapter will work with Psion’s corporate and personal 
email applications and standard communications applications. Current 
versions of 3Fax software will not work with the PC Card Modem Adapter. 
New versions of 3Fax software, renamed as PsiFax, are available to work 
with the adapter. 


EN55022, EN500082-1 
EN60950 


118.5mm x 91mm x 20.5 mm 
105g without batteries 


Siemens C165 16 bit micro-controller 
OTP. 


4 x AA batteries 
and/or 
6V DC/1A mains adapter 


Depends on the modem card you use. 
With a Psion Dacom 28.8 modem, typically 90 to 120 mins (Duracell 
batteries). If the unit is unused, approximately 6 months (Duracell batteries). 


Series 3a variant: SIBO Fast Serial (ASIC5) 
Series 3c variant: RS232 
PC variant: RS232 


A single LED and piezo buzzer. The LED flashes according to the status of 
the PC Card adapter (transmitting, low power warnings etc.). The piezo 
buzzer provides modem tones, dial tones and bleeps with recognition when a 
PC Card modem is inserted into the adapter. 


For connection to the computer: 

Series 3a variant: 6-way two row rectangular (female) custom plug 
Series 3c variant: Low Profile Honda type custom connector 

PC variant: 9-way D type connector 


For connection to the PC Card modem: 
PCMCIA standard connector 


SERIES 3/3A PROGRAMMING GUIDE 


Supported PC Cards: 


DTE formats 
Flow control 


Data transfer rates: 


Indicator LED 


Psion Dacom Gold Card 

US Robotics WorldPort 

Pace Microlin 

Megahertz X JACK Series 
Nokia Cellular Data Card 
Philips Mobile Data Card 
Hayes PC Cards 

Dr. Neuhaus Fury Cards 

and many other popular models 


PC Modem Cards can be inserted at any time and recognised by the card 
adapter (hot swapping) 


8N1,7E1,701 
RTS/CTS 


300 Baud to 57.6 KBaud with autobauding 
300 Baud to 115 KBaud without autobauding 


Note: Because Psion Fast Serial operates at a maximum 19.2kbs the user will 
not be able to get the full 33.6 KBaud data rate available from V.34 PC 
Cards in the Series 3a variant of the PC Card Adpter. In this scenario the 
connection rate will drop down to 14.4 KBaud. 


to/from 
Psion 


Indicator LED 


Status On Batteries On Mains 

Stand by Off Flashing green (slow) 
Idle Flashing green (slow) Flashing green (slow) 
Configuring PC card Flashing green (fast) Flashing green (fast) 
Connected to remote modem Continuous green Continuous green 
Low battery warning Flashing red N/A 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Psion Travel Modem Technical Specification 


Physical 

Part number: 

Series 3/3s compatibility: 
Series 3a compatibility: 
Workabout compatibility: 
Series 3c compatibility: 
Siena compatibility: 
EMC: 

Environment: 


Dimensions: 


Power: 


Communications 


Functions: 


Dialling: 
Echo suppressor: 
REN: 


Fax operation: 


Computer connection 


Connector: 


Network connection 


Data transfer rate: 


FCC Part 15 Class B; CE Mark 


Operating temperature: 0-50C 
Operating humidity: 0-95% non-condensing 


165mm x 40mm x 25mm 
2 x AA batteries or 


optional rechargeable NiCad battery pack or 
optional 10V (250mA) DC Series 3c mains adaptor. 


Autodialling (tone and pulse) modem conforming to: 
V.21,V.22, V.23, V.22bis, V.27ter, V.29, V 32 and V 32bis standards. 
It supports V.25 auto answering recommendations. 


May be used with either tone (MF) or pulse (LD) signalling BT lines. 
Echo-suppressor tone (V25) when auto answering. 
1. 


Controlled automatically by software (not supplied with the Travel 
Modem). 

The Travel Modem can send faxes at up to 9600bps. 

The fax feature is compatible with Group 3 fax machines. 


Low Profile Honda type custom connector on flying lead 

for connection to a Psion Series 3c. 

See the 'Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


up to 57600bps with V.32bis and V.42bis 
(compression is dependant upon file type) 
V.32 9600 bps full duplex 

V.32bis 14400 bps full duplex 


SERIES 3/3A PROGRAMMING GUIDE 


Operational modes: 


Line connection: 
Signal level: 


Equalisation: 


Interface: 


Error correction: 


Data compression: 


Autodial/autoanswer 
Dial method: 


Call progress: 


Call control: 
Automatic answer: 


Mode selection: 


Call disconnection: 


BABT Approval 


Approval number: 


V.21 300bps full duplex 

V.22 1200bps full duplex 

V.22bis 2400bps full duplex 

V.23 1200/75 full duplex 75/1200 full duplex 
V.27ter 4800bps fax send and receive 

V.29 9600bps fax send and receive 


2 wire PSTN via BT 600 type modular jack on flying lead 
-9 dBm 


Transmit fixed compromise 
Receive automatic adaptive 


600 ohm 


V.42 incorporating LAPM and MNP Class 4 
MNP Class 10 


V.42bis and MNP Class 5 


Tone or pulse, selectable 


Loudspeaker with on/off control 
Extended results codes 


Extended "AT" command set 
To CCITT V.25 recommendation 


Automatic configuration to V.21/V.22/V.23/V.22bis and V32/V32bis on 
receive 


Loss of carrier, DTR or by command 


606866 


Psion 3Fax Modem Technical Specification 


The 3Fax modem has been superseded by the Series 3a PC Card Adapter with a suitable PC Card modem, 
combined with the PsiFax software on SSD, (for the Series 3c there is the Travel Modem). 


Physical 


Part number: 


Series 3/3s compatibility: 


Series 3a compatibility: 


Workabout compatibility: 


Series 3c compatibility: 
Siena compatibility: 
EMC: 


Environment: 


Dimensions: 


Power: 


1601-0022-01 


No 
Yes (512KB, IMB and 2MB models only) 
No 


FCC Part 15 Class B; CE Mark 

Operating temperature: 0-50C 

Operating humidity: 0-95% non-condensing 
165mm x 40mm x 25mm 


2 x AA batteries or 
optional rechargeable NiCad battery pack or 
optional 10V (250mA) DC Series 3a mains adaptor. 


Communications 


Functions: 


Dialling: 
Echo suppressor: 
REN: 


Fax operation: 


Computer connection 


Connector: 


Network connection 


Data transfer rate: 


Operational modes: 


Line connection: 


Signal level: 
Equalisation: 


Interface: 

Error correction: 

Data compression: 
Autodial/autoanswer 
Dial method: 

Call progress: 


Call control: 
Automatic answer: 
Mode selection: 
Call disconnection: 


BABT Approval 


Approval number: 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Autodialling (tone and pulse) modem conforming to: 
V.21,V.22, V.23, V.22bis, V.27ter, and V.29 standards. 
It supports V.25 auto answering recommendations. 


May be used with either tone (MF) or pulse (LD) signalling BT lines. 
Echo-suppressor tone (V25) when auto answering. 
1. 


Controlled automatically by the software supplied with the 3Fax modem. 
The 3Fax modem can send faxes at up to 9600bps. 
The fax feature is compatible with Group 3 fax machines. 


6-way two row rectangular (female) plug 

for connection to a Psion Series 3a. 

See the 'Reduced External Expansion’ section of the 'SIBO Expansion Ports' 
chapter in the Hardware Reference manual for pinout details. 


up to 9600bps with V.22bis and V.42bis 
(compression is dependant upon file type) 


V.22bis 2400 bps full duplex 

V.22 1200 bps full duplex 

V.23 1200/75 full duplex 75/1200 full duplex 
V.21 300 bps full duplex 

V.27 ter 4800 bps fax send and receive 

V.29 9600 bps fax send and receive 


2 wire PSTN via BT 600 type modular jack 
3 wire Bell Tinkle Suppression supported 


-9 dBm 


Transmit fixed compromise 
Receive automatic adaptive 


600 ohm 
V.42 incorporating LAPM and MNP Class 4 
V.42bis and MNP Class 5 


Tone or pulse, selectable 


Loudspeaker with volume control 
Extended results codes 


Extended "AT" command set 

To CCITT V.25 recommendation 

Automatic configuration to V.21/V.22/V.23 & V.22bis on receive 
Loss of carrier, DTR or by command 


NS/1397/3/R/604375 


The greyed out table is statutory statements and not really part of the tech spec 


Nokia 21XX to Series 3c/Siena SMS Cable 
- Technical specification 


This SMS cable is available from the beginning of January 1997. 
This SMS Link cable connects a Psion Series 3c or Siena to Nokia’s 21XX range of GSM/DCS/PCS 


digital mobile phones. 


The cable is for use with applications based on version 2.01 of the SMS SDK running on a Siena or 


Series 3c. 


The top level Psion part number for this SMS cable is 1601- 0106 -01. 


SERIES 3/3A PROGRAMMING GUIDE 


Ericsson SMS SDK and SMS Cables 


There will be 2 types of SMS products: 


e SMS SDK - enables Psion Registered Developers to create applications for both vertical and 
horizontal markets that make use of the SMS capability provided by Ericsson’s GSM/DCS/PCS 
digital mobile phones; 


e SMS applications and SMS cables - Shrink wrapped and custom SMS applications available 
from both Psion and its Registered Developers. These applications will be invariably be packaged 
with the Ericsson SMS cable to connect the Psion to the Ericsson mobile phone. 


The SMS SDK will be released to selected registered developers from the end of December 1996. 
The SMS SDK is distributed for free. 


Product Description 


Ericsson SMS SDK 
The SMS SDK provides the following capabilities: 


e Mobile Originate (MO) and Mobile Terminate (MT) of SMS messages; 
e Access to the address book memory within the phone and SIM; 

e Sensing of key presses and screen indications on the phone; 

e Ability to send the full range of key presses from the Psion to the phone; 
e Sensing the model number and firmware version of the phone; 

e SMS delivery status reports (DSRs). 


SMS cables 


An SMS Link cable connects a Psion Series 3c or Siena to Ericsson’s GSM/DCS/PCS range of digital 
mobile phones (GH377, GF388, GA318, PH337, CH337 etc.) 


Note: Ericsson SMS links will not be available for the Psion 3a. 


The interface between the Ericsson handset and Psion 3c/Siena is housed within the Ericsson connector, 
thus providing the user with only a thin cable connection. 


The top level Psion part number for this SMS cable is 1601-0107-01. 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Cellnet SMS/ink 


Cellnet SMSlink is a joint development between Cellnet and Psion. It is an SMS product for the popular 
Series 3a and Nokia 2110 combination. 


The Product includes: 
e Cable to connect Series 3a to Nokia 2110/2110i, and Philips PR747 GSM mobile phones 
e Series 3a software for composing, sending and receiving text messages 


e PC software (on floppy disc) to send text messages direct from PC to GSM mobile phones. 
(Requires a modem) Note: This is Freeware supplied by Cellnet. 


e User Guide 
Cellnet SMSlink allows you to: 
¢ Compose, edit, send and receive short messages of up to 160 characters 
e Simple message management using the inbox and outbox, and unread message box 
e Send and receive electronic business cards 
e Send messages to a selected group of contacts 
e Incorporates a contact manager similar to the built-in Data application 
e Works with contact databases generated using Data or compatible applications 
e Sort and search on contact database entries 
e¢ 10 pre-set messages, and you can also create your own. 
e Appointment details sent in a message may be extracted and merged with Agenda. 
Compatibility 
Compatible with Psion Series 3a computers - 512k and above 


This application will be distributed on SSD and floppy disk. Floppy disc version requires PsiWin or 3link 
for installation. 


Version Top level part number 


SSD: 1601-0065-01 


Floppy disc: 1601-0066-01 


Availability 


Has been available from August 1996. 


Please Note: Our license with the development company only allows us to market this product in the UK. 
Therefore it is not available to export markets. 


SERIES 3/3A PROGRAMMING GUIDE 


Vodaphone Telenote Link 


Vodaphone Telenote Link is a joint development between Vodaphone, Nokia and Psion. It is an SMS 
product for the popular Series 3a and Nokia 2110 combination. 


Versions 
There are two versions of the Telenote link: 


e Version 1, (available from the beginning of December 95), is for use with the Nokia 2110 and 
Philips PR747 digital handsets; 


e Version 2, (available from February 96), is for use on the Orbitel 905 digital handset. 
The product is issued either on SSD and floppy disk. 


System Requirements 


Telenote Link requires a Psion Series 3a 256K or larger internal RAM palmtop computer, or a Psion 
Workabout, and a Nokia 2110 (or equivalent) digital phone on the Vodafone digital mobile phone 
network. 


The Telenote Link product includes software for a PC which allows its user to originate messages, and 
using a modem, (not supplied) to dial direct into the Vodafone Short Message Centre. 


Telenote Link Functions 


The Vodafone Telenote Link for the Psion Series 3a allows the user you to create, store and receive short 
messages in a simple intuitive manner using his Series 3a and Nokia GSM phone. The software for the 
Series 3a also includes a comprehensive address book function and the ability to create frequently used 
messages (e.g. “Please call me”, or “I will be 15 minutes late for the meeting”), which can be sent quickly 
with a minimum number of key strokes. 


The Telenote Link product allows the user to: 


e Send messages from his Series 3a and Nokia phone to another handset on the Vodafone GSM 
network, or any other GSM network world-wide which supports SMS and with which Vodafone 
have a roaming agreement; 


e Send messages from a PC (provided the user already has a modem) to any GSM handset on the 
Vodafone network (this feature will work with handsets other than those based on the Nokia 
2110). 


The Telenote Link product does not allow the user to: 
e Send or receive SMS to/from a Cellnet, Orange or Mercury digital phone; 


e Send or receive SMS to/from a phone on a network which does not support SMS, or with which 
Vodafone does not have a roaming agreement. Most foreign GSM networks will support it, but 
some (particularly France) are behind in deploying the service; 


e Send or receive e-mail to/from his Series 3a/Nokia; 
e Send or receive Faxes to/from his Series 3a/Nokia. 


Telenote Link Package 
The Telenote Link Package includes: 


¢ Cable to connect a Series 3a to Nokia 2110 (or derivatives such as Philips) GSM phones on the 
Vodafone network; 


e Software for the Series 3a supplied on floppy disk or SSD. Floppy disk software (requires a PC 
and PsiWin to download to Series 3a); 


e Software for a PC allowing use of a modem (not supplied) to direct dial into the Vodafone Short 
Message Centre, allowing the user to originate messages from his desktop. This is particularly 
useful for a receptionist/secretary who needs to pass on messages to somebody who is away from 
the office; 


¢ Comprehensive user guide. 


APPENDIX A: TECHNICAL SPECIFICATIONS 


Version Top level part number 


SSD: 1601-0057-01 


Floppy disc: 1601-0056-01 


Availability 


Current product. 


Orange Messaging Link 


Orange Messaging Link is a joint development between Orange and Psion. It is a messaging product 
which is based on the GSM SMS service but for the Orange network. (Orange is a Personal 
Communications Network (PCN) which uses GSM technology but at a higher frequency and with lower 
power handsets) It works with Series 3a and Nokia Orange and Nokia Orange 5.1 handsets. 


The product includes: 
e Cable to connect Series 3a to Nokia Orange and Nokia 5.1 handsets 
e Series 3a software for composing, sending and receiving text messages 
e User Guide 


e A guide prepared by Orange on how to access their network from a PC with a modem to send 
messages. 


Orange Messaging Link allows you to: 
e¢ Compose, edit, send and receive short messages of up to 160 characters 
e Simple message management using the Sent, Received, Not sent, and Phonebook dialogues 
e Send messages to a selected group of contacts 
e Works with contact databases generated using the series 3a Data application. 
e Create your own preset messages 
Compatibility 
Compatible with Psion Series 3a computers - 512k and above 


This application software is distributed on SSD or floppy disk. The floppy disc version requires PsiWin or 
3Link for installation. 


Version Top level part number: 


SSD: 1601-0067-01 


Floppy disc: 1601-0068-01 


Availability 
Available from mid-November 1996. 


Please Note: Our license with the development company only allows us to market this product in the UK. 
Therefore it is not available to export markets. 


APPENDIX B 


DIFFERENCES BETWEEN PSION SERIES 3 MODELS 


At the time of writing there are four current and six superseded machines in the Series 3 family. The main 
differences between the computers are tabulated overleaf. 


SERIES 3/3A PROGRAMMING GUIDE 


Current models in the Series 3 family 


SSD drives 2 2 optional optional 
extra extra 


Communications connector R232 R232 R232 R232 
low profile, low profile, low profile, low profile, 
with power with power with power with power 
output output input input 


Time management/organiser 
- Open book diary with reminder alarms day/week day/week day/week day/week 


- Planner views year/busy year/busy busy busy 


- 'Things to do' manager multiple lists | multiple multiple multiple 
with due lists with lists with lists with 
dates and due dates due dates due dates 
alarms and alarms and alarms and alarms 


- Chronological list and anniversaries view 3 3 


3 3 
Voice/sound recording and playback “Sound” “Sound” 
Ea al 
desk, desk, desk, desk, 
advanced advanced advanced advanced 
Ee ( 
Le 
Fax facility (send only) optional optional a 
extra extra 
Zoom-in zoom-out through four font sizes 
Spellchecker and Thesaurus optional optional 
extra extra 
eee ee 


APPENDIX B: DIFFERENCES BETWEEN PSION SERIES 3 MODELS 


aia eh iacite models in the Series 3 ay 


Ea 
(* 2MB if Spell app included) 512KB 512KB 
a ee 


SSD drives 
Communications connector 


Time management/organiser 
- Open book diary with reminder alarms day/week day/week day/week day/week 


- Planner views year year year year 


- 'Things to do' manager multiple multiple multiple multiple single list, single list, single list, 


lists with lists with lists with lists with up to 50 up to 50 up to 50 
due dates due dates due dates due dates items items items 
and alarms and alarms and alarms and alarms 


- Chronological list and anniversaries view 


optional 
extra 


Fax facility (send only) optional optional optional 
extra extra 


Pee ger enye a ee es ee Ee |e ee 


Communications application 3 3 3 3 optional optional optional 
extra extra extra 


Rich text file (RTF) support optional optional optional optional optional 
extra 


Spellchecker and Thesaurus optional optional optional 
extra 


Patience card game optional optional 
extra 


Ec (AE 


INDEX 


.afl files 
add file lists pre-defined slots $3, 1-2 
add file lists $3, 1-2 
als files 
creating .als files S3, 2-5 
creating with makeals.exe $3, 2-5 
.app files 
versus .img files, 1-2 
.img files 
versus .app files, 1-2 
.ma files 
alias file source file $3, 2-5 
.ms files 
multi-lingual $3, 2-3 
shell data file source file $3, 2-1 
.pcex files 
converting to icon files, 1-3 
pic files 
application icons $3, 1-2 
sc files 
resource files application S3, 1-2 
zc files 
resource files compressed S3, 1-2 
.shd files 
application S3, 1-3 
creating with makeshd.exe S3, 2-1 
customised $3, 1-3 
multi-lingual $3, 2-2 
shell data files $3, 1-2 
3Fax modem 
data compression, A-15 
modes, A-15 
3Link parallel 
specification, A-10 
3Link PC serial 
Apple Macintosh converter, A-7 
assembly components, A-7 
3Link serial cable 
specification, A-5 
9-to-25 way D-type adapters 
specification, A-9 
9-to-25 way D-type modem adapters 
wiring diagram, A-9 
9-to-25 way D-type PC (XT) adapters 
wiring diagram, A-9 
9-to-25 way D-type printer adapters 
wiring diagram, A-10 
adapter - PC card modem 
specification, A-11 
adapters 9-to-25 way D-type 
specification, A-9 
adaptor cable 
modem - 3Link, A-7 


adaptor cable modem 


Mac Link, A-8 
PC Link, A-8 
add file list 


application pre-defined slots $3, 1-2 
application S3, 1-2 
add files 
finding in an app file S3, 1-3 
alias files 
creating from .ma source files S3, 2-5 
creating with makeals.exe $3, 2-5 
aliasing 
applications active $3, 2-5 
applications active Word app S3, 2-5 
applications mechanisms S3, 2-6 
applications passive S3, 2-5 
applications S3, 2-4 
creating .als files S3, 2-5 
Word app multi-lingual S3, 2-13 
Apple Macintosh 
3Link - convertion from PC 3Link, A-7 
application 
add file finding in app files $3, 1-3 
add file lists pre-defined slots $3, 1-2 
add file lists $3, 1-2 
alias .als files creating $3, 2-5 
alias file creating from .ma files S3, 2-5 
aliasing active S3, 2-5 
aliasing active Word app S3, 2-5 
aliasing mechanisms S3, 2-6 
aliasing passive S3, 2-5 
aliasing S3, 2-4 
aliasing Word app multi-lingual $3, 2-13 
app files vs img files, 1-2 
button assigning system screen S3, 2-8 
button assignments system screen S3, 2-8 
comand line command byte S3, 2-10 
comand line debugger and S3, 2-10 
comand line disregarding S3, 2-11 
comand line handling S3, 2-9 
command line absent $3, 1-3 
command line byte new types S3, 2-13 
command line format of $3, 2-9 
command line handling S3, 2-10 
compatibility S3/3a/Workabout, 1-5 
compatibility S3/S3a/S3c/Siena, 1-5 
default directory S3, 2-2 
default file extension $3, 2-2 
directories creating as needed S3, 2-12 
example Spy Hwif, 4-1 
heap integrity Spy app, 4-2 
heap statistics Spy app, 4-2 
icon files, 1-2 
icons producing, 1-3 
icons with or without $3, 1-3 
multi-lingual keyboard S3, 1-4 
multi-lingual menu accelerators S3, 1-4 
other data Spy app, 4-3 
process priorities Spy app, 4-2 
public name S3, 2-2 
resource .rsc files, 1-2 
resource files .rzc compressed S3, 1-2 
running via Runimg S3, 1-3 
segment statistics Spy app, 4-2 


SERIES 3/3A PROGRAMMING GUIDE 


shell data files creating from .ms files S3, 
2-1 

shell data files customised S3, 1-3 

shell data files multi-lingual $3, 2-2 

shell data files S3, 1-2, 1-3 


shell data source files multi-lingual $3, 2-3 


shut down message absent S3, 1-3 

shut down message S3, 2-12 

Spy, 4-1 

Spy building, 4-1 

Spy main display, 4-1 

Spy source code, 4-1 

Spy system processes, 4-1 

stack statistics Spy app, 4-2 

switch file message absent S3, 1-3 

switch files message S3, 2-12 

system message receiving S3, 2-12 

system screen command line message S3, 
2-13 

system screen communications S3, 2-1 

system screen message handling S3, 2-12 


system screen shut down message S3, 2-12 
system screen switch files message $3, 2-12 


type numbers S3, 2-2 

type pure file list S3, 2-4 

window server statistics Spy app, 4-3 
button 

assigning in system screen $3 apps, 2-8 


assignments in system screen S3 apps, 2-8 


cable adaptor 

modem - 3Link, A-7 
cable adaptor modem 

Mac Link, A-8 

PC Link, A-8 
command line 

absent application $3, 1-3 

command byte S3 apps, 2-10 

debugger and S3 apps, 2-10 

disregarding S3 apps, 2-11 

format of S3 apps, 2-9 

handling S3 apps, 2-9, 2-10 

magic statics updating S3 apps, 2-11 

new command byte types S3, 2-13 

new for system screen message S3, 2-13 
comms 

3Fax modem data compression, A-15 

error correction, A-14, A-15 

Travel Modem data compression, A-14 
compatibility 

S3/S3a/S3c/Siena apps, 1-5 

S3/S3a/Workabout apps, 1-5 
DatApp1 

magic static system screen S3, 2-8 
DatLocked 

magic static $3, 2-7, 2-9 
DatProcessNamePtr 

magic static $3, 2-7, 2-8 
DatStatusNamePtr 

magic static $3, 2-7, 2-9 
DatUsedPathNamePtr 

magic static $3, 2-7, 2-8 
debugging 

magic statics $3 apps, 2-7 
directories 


creating as needed S3 apps, 2-12 
directory 
default S3 app, 2-2 
environment variable 
naming of, 1-5 
Series 3, 1-4 
EPOC 
magic statics $3, 2-7 
file list 
application type pure S3, 2-4 
file lists 
files with hidden attribute S3, 2-8 
system screen and S3 apps, 2-7 
system screen name with Sys$ $3, 2-7 
file name 
extension default S3 app, 2-2 
heap integrity 
Spy application, 4-2 
heap statistics 
Spy application, 4-2 
Hwif 
application example Spy, 4-1 
application magic statics S3, 2-7 
HWIM 
application magic statics S3, 2-7 
icon files 
application S3, 1-2 
contents and formats, 1-3 
converting from .pcx, 1-3 
production of, 1-3 
Iconed 
producting icon files, 1-3 
Macintosh 
3Link - PC serial converter, A-7 
Macintosh link cable 
specification, A-8 
magic static 
command line updating S3, 2-11 
DatApp1 system screen S3, 2-8 
DatLocked §3, 2-7, 2-9 
DatProcessNamePtr S3, 2-7, 2-8 
DatStatusNamePtr S3, 2-7, 2-9 
DatUsedPathNamePtr S3, 2-7, 2-8 
debugging and S3 apps, 2-7 
Hwif and S3 apps, 2-7 
HWIM and S3 apps, 2-7 
Series 3/3a, 2-7 
system screen S3 apps, 2-7 
window server S3 apps, 2-7 
makeals.exe 
alias files creating S3, 2-5 
makeshd.exe 
utility program, 2-1 
modem 
3Fax modem modes, A-15 
Travel modem data compression, A-14 
Travel Modem modes, A-14 
modem - 3Fax 
specification Series 3, A-14 
modem - PC card adapter 
specification, A-11 
modem adapters 9-to-25 way D-type 
wiring diagram, A-9 
modem adaptor cable 


3Link, A-7 
Mac Link, A-8 
PC Link, A-8 
modem -Travel 
specification, A-13 
multi-lingual 
aliasing Word app S3, 2-13 
multi-lingual apps 
keyboards S3, 1-4 
menu acceleratiors $3, 1-4 
other data 
Spy application, 4-3 
parallel 3Link 
specification, A-10 
parallel printer link cable 
specification, A-10 
PC (XT) 9-to-25 way D-type adapters 
wiring diagram, A-9 
PC card modem adapter 
specification, A-11 
PC Link cable 
specification Series 3c/Siena, A-8 
PC serial 3Link 
Apple Macintosh converter, A-7 
assembly components, A-7 
printer 9-to-25 way D-type adapters 
wiring diagram, A-10 
printer cable serial 
specification Series 3a), A-7 
specification Series 3c/Siena), A-8 
printer parallel link cable 
specification, A-10 
process priorities 
Spy application, 4-2 
program files 
icons with or without $3, 1-3 
programming 
Series 3 choices, 1-1 
Series 3 overview, 1-1 
public name 
application S3, 2-2 
REN 
ringer equivalence number, A-15 
ringer equivalence number modem, A-13 
reserved statics 
see magic static, 2-7 
resource files 
application .rsc $3, 1-2 
application .rzc compressed S3, 1-2 
ringer equivalence number 
modem, A-13 
modem), A-15 
Runimg 
application running from S3, 1-3 
segment statistics 
Spy application, 4-2 
serial 3Link 
assembly components - PC serial, A-7 
serial 3Link cable 
specification, A-5 
serial link 
specifications 3Link cable, A-5 
serial printer cable 
specification Series 3a), A-7 


INDEX 


specification Series 3c/Siena), A-8 
Series 3 
environment variables, 1-4 
programming choices, 1-1 
programming overview, 1|-1 
sound device driver MUS:, 3-1, 3-2 
sound driver de-installing sndfre.ldd, 3-4 
sound driver installing sndfrc.ldd, 3-1, 3-4 
sound driver snddvr.ldd, 3-1 
sound driver sndfrc.ldd, 3-1 
sound enhanced, 3-1 
specifications 3Link cable, A-5 
specifications modem 3Fax, A-14 
Series 3 models 
differences between, B-1 
Series 3/3s 
specifications, A-2 
Series 3a 
sound, 3-4 
sound device driver SND:, 3-1, 3-4 
sound example code, 3-5 
sound simultaneous, 3-1 
specifications, A-1 
Series 3c 
specification, A-3 
shell application 
communicating with S3, 2-1 
shell data files 
application S3, 1-2, 1-3 
application type numbers S3, 2-2 
creating from .ms files S3, 2-1 
creating with makeshd.exe S3, 2-1 
customised S3, 1-3 
default directory S3 app, 2-2 
default file extension S3 app, 2-2 
multi-lingual $3, 2-2 
source .ms files $3, 2-1 
source multi-lingual $3, 2-3 
shut down 
absent message application S3, 1-3 
message handling S3 apps, 2-12 
SIBO 
Series 3 models - differences, B-1 
Siena 
specification, A-4 
Siena SSD drive 
specification, A-5 
sound 
device driver MUS: Series 3, 3-1, 3-2 
device driver SND: Series 3a, 3-1, 3-4 
driver snddvr.ldd Series 3, 3-1 
driver sndfrc.ldd de-installing Series 3, 3-4 
driver sndfrc.ldd installing Series 3, 3-1, 
3-4 
driver sndfrc.ldd Series 3, 3-1 
enhanced S3, 3-1 
Series 3a, 3-4 
Series 3a example code, 3-5 
simultaneous Series 3a, 3-1 
specification technical 
9-to-25 way D-type adapters, A-9 
Macintosh link cable, A-8 
parallel 3Link, A-10 
parallel printer link cable, A-10 


iii 


SERIES 3/3A PROGRAMMING GUIDE 


PC card modem adapter, A-11, A-13 
PC Link cable Series 3c/Siena, A-8 
printer - parallel link cable, A-10 
serial printer cable Series 3a, A-7 
serial printer cable Series 3c/Siena, A-8 
Series 3 - 3Link cable, A-5 
Series 3/3s, A-2 
Series 3a, A-1 
Series 3c, A-3 
Siena, A-4 
Siena SSD drive, A-5 
Travel modem, A-13 
specifications technical 
modem 3Fax Series 3, A-14 
Spy 
application, 4-1 
application building, 4-1 
application heap integrity, 4-2 
application heap statistics, 4-2 
application main display, 4-1 
application other data, 4-3 
application process priorities, 4-2 
application segment statistics, 4-2 
application source code, 4-1 
application stack statistics, 4-2 
application system processes, 4-1 
application window server statistics, 4-3 
SSD drive - Siena 
specification, A-5 
stack statistics 
Spy application, 4-2 
statics reserved 
see magic static, 2-7 
switch file 
absent message application S3, 1-3 
switch files 
message handling S3 apps, 2-12 
system processes 
Spy application, 4-1 
system screen 
assigning application buttons S3, 2-8 
communicating with S3, 2-1 
current file $3, 2-1 
file list names with Sys$ $3, 2-7 
file lists and S3 apps, 2-7 
files with hidden attribute S3, 2-8 
magic statics $3 apps, 2-7 
message handling S3 apps, 2-12 
message receiving S3 apps, 2-12 


new command line message S3 apps, 2-13 
shut down message handling S3 apps, 2-12 


shut down message S3, 2-1 
status window S3, 2-1 


switch files message handling S3 apps, 2-12 


switch files message S3, 2-1 
system screen 
magic static DatApp1 S3, 2-8 
Travel modem 
specification, A-13 
type numbers 
applications S3, 2-2 
utility program 
makeals.exe alias file utility, 2-5 
makeshd.exe shell data file utility, 2-1 


window server 
magic statics S3 apps, 2-7 
statistics Spy application, 4-3 
wiring diagram 
9-to-25 way D-type modem adapters, A-9 
9-to-25 way D-type PC (XT) adapters, A-9 
9-to-25 way D-type printer adapters, A-10 
Word application 
aliasing active example S3, 2-5 
WSpCx.exe 
converting .pcx files to icon files, 1-3