diff --git a/docs/1-01 General Programming Manual 2.30_djvu.txt b/docs/1-01 General Programming Manual 2.30_djvu.txt new file mode 100755 index 0000000..5669268 --- /dev/null +++ b/docs/1-01 General Programming Manual 2.30_djvu.txt @@ -0,0 +1,4877 @@ +SIBO 'C' Software Development Kit + + +GENERAL PROGRAMMING MANUAL + + +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 Installation .............csccsssssssscssscrssssceeeeseeeseeeseesseesssesseesseesseesseesseesseesseesseesceesceesseescesscsscesoseesoeees 1-1 +Installation: :: i328 Assisi Aces whe chad Oks Ahsdoke sneha saniiin 1-1 +Dif CtOry StEU Chute css 259s sie, Boost eek os shsg eats tess eth clees da Dies cos thes oT Dees ous hes eb Tset vous Teeneeeaav 1-2 +Reconfiguring the TopSpeed project SysteM...........cssessecssseeesneecsseecsseeceseeeesaeessaeers 1-2 +Customising the redirection file... eee eeeesesccssneeceneecseecsseecsseeeesseessaeecsaeesssneeessaes 1-3 +2 A Brief Overview Of The SIBO SDK...............scsscsssssssssesesssesssessscsssesssessesesssessseessesssesssessoeees 2-1 +Mantlal si as tcas crest a tacit a ptiteseder chai abste bei eiea ide ahr ianohii ast 2-1 +WHEE TO SCALE sis ont 0k cee sat can abet ech veits es AlN oeuviuat ses alts cavvainases Ud oetitialens Gioia oe 2-2 +The terms SIBO and EPOC explained ..........ceeceeceseseecsseessseeceseeeesaeeesaeecsaeeesseeessaes 2-2 +Fatal programming errors (Pamics) .........ceseeeseeceseeessceeesseecsseecsaceceeecesaeeesaeesseessneeeeseaeers 2-3 +Panic NUMDers :s..s:205 iors hess devas Gales eee eek bigs vaneiens ian Ghee 2-3 +C++ and Object Oriented programming ...........eesceeseeceseeceseeesseeseeecseeeseseeeesaeessaeesseeesee 2-3 +3 Building An Application ...............csscccssscssssccsscsssscsssssssssscsssecsssecsssssssssssssscnssscsessesssssssesseesees 3-1 +INtroduchOti sais cei eh ab de ash kd Heh ah ee lg 3-1 +Equipment required: :ctics 2 otesscvsthsce soba. cosa doee nesdussceusonasuestuaccavediseseassysoansibensseussaes 3-1 +Whichfilesare needed 2.5. ccsscusi.5 coves cavsciestidebeccheves iol stebeset evveieh Steee sed seveted ees etlvber 3-2 +Avfirst: éxample-applCattonicsssi.ci.tsiscssteasactealasieestesisceat le doenteaietenulads. agancdelasieesascaendst 3-2 +A first look at projectiles o 525; ccissckeuei Seuscbehsiengotd Seubebetsaesaoch yuh veh sdebaten ouoh evshcgubeoeh Suenee 3-2 +Creating: the ime filet:4 iain ohana lan ouB asian lanl 3-3 +Copying the program to the target Machine ........ eee eeeeceeneeeeeeceeesseessseeessaeeesaee 3-3 +Running the program on the target COMPULET........... ee eeeeeeeeneeeeneeceneeseaeessseeeeteeeesaee 3-3 +Stepping through the program with the SIBO Debugger .......... eee eeeeeeseeeeseeeeeeeeenes 3-4 +A PEIB version Of Hello Wotldssssis.scccbes.ceadeseseepiessc svda deste hiss apsviebe abtbies aeessarboeeeescbaae 3-4 +PEIB- and ‘CLIB conitrasted oi. sc... 205 sicse eves cevetul sees teas caved ub steve neste. fel stevssustevbs felseeseesstyl 3-4 +The-code for p hello. i drcssectssvestasscasseaiate adacteostea lareadaadenstestaseendsieasteataceenderioes eters 3-5 +The epocinit statement in -pr files... eee eee eeseeesseeceseeesseeeeseeeesaeecsaeesseeesneessnaeeesaes 3-6 +Housekeeping batch files and re-using project files... eee eeseeeseeceseeeeeeeeesseeesaeessneeeees 3-6 +A general project file: unnamed. pF oe. eee eeeeeeeseeceseeesseesseeceseeeesaeeesaeessaeessseeeesaes 3-6 +A batch file for test Compilation .......... eee eeeeeeseeesseecsneeceseeeesaeeesaeecsaeecsaeessneeeeteeeesaes 3-6 +SOME COMPLICALLONS. os 2565 55h sete oks Fe heh ios Povk a gheties Soe Sivd ou gh adieba Sen usd bu gb ctuboveu dunk aubetedo tue 3-7 +TSE versus ISCX i sssiostiss Mann eatin Aeniisscess teas dapbescrsp bate sapdasecesp hase aspbebs evades vundays 3-8 +More complicated programming SeCtUPS ..........:.csscessseceseeceseeeceseeceaeecseecseaeeesaeecsaeessneeeees 3-9 +Simple: PEIB: examples. sis.2ccasiasesetasicasagiasventaalateesbaadvestaasatessdawdoestestavesetaaateatagsgers 3-9 +Moulti- file: prograinss.i sc castsisiceiiecigasl a sccbehicskpth auhcvelceeheoek Sheicvehjesbepehoigievesdestek sist 3-9 +Graphics programs. ::..2.5:4 cp mstdceai Mapas dete Aeiiesicnipiensdapbeadseteti ss dngiescAeetise deeds 3-10 +FAWIP progranns csc ossi0s cossccts tours cds Faveeubedevsesdsduyacad edu vse sdsdueaeevsdvetesds svneebsteesecosteensvbanes 3-10 +Customised) libraries ¥s.::2)c<.t2s.ss555.92.diabateansaiste ddatpeatacisgeeleahe asibasounlastetestansendastoees 3-10 +Applications containing assembler as Well aS Cu... eee eeeeceeseeceseeeesneeseeeesseersaeeseeeeees 3-11 +Other advanced use of the project file SySteM..........esceesceeessceeesneeceseeceneeceseeeesaeessaeers 3-11 +Greater control over the image file created... eee eeeeeseeesneessneeceeeeceeeesaeeesaeeesaeersneeenee 3-12 +Priority, minimum heap, and version NUMDET............: ce eeeeeseesneeeeneeceneeceseeeseeeeneeeesaes 3-12 +Use.OF Edumipiex rc. isiiit jf it ievieta Mis nhee Mi Ane oeiicciad sie eaten ile sed 3-12 +Differences between .app files and .1mg files 0.0.0... eles eeeeeesneeeeneeceeeceeeeseeeeseeeesaes 3-13 +Ad d=file ist si... ess Seeose ed Stbbe ous oP ysis saubease Sevseeesebsdis TeesesbeSas RIP Ivers thus nerve eres 3-13 +Changing the set of add-files in an 1Mage......... eee eeeeeeeseeceseeeseecsaeecsseeeeseeeesaeeseaeers 3-14 + + +Further uses of emake.exe ............ccccccceseeseccccccceeessseccccssseeeesseecccsssseueeseescessssueeeseeessess 3-14 + + +GENERAL PROGRAMMING MANUAL + + +ii + + +4 Notes On CLIB.............sccssssssscssscsssesssessserssesssesssesssesseesssssssesssesssesssesssesssesseesssessesseessseessesseeeseees 4-1 +Functions missing from the MS-DOS JPIC library... eee eeeeeseeesseeeeseeeeeneeeeneees 4-1 +TAS OR 5s deste ces; cass nevedeepavstbs sb eeagbassdact salscesodanpdhugasasevacespdensosbi cusses sosevehes Aantensseeraion tes 4-2 +DIVE eset rt MM eR el oa NN oe ah oe te eee area ones ute aa PEG cara eset hs 4-2 +File handle conversion routine............ceeseseseecsscecesceesseecseecseecsseeeesaeecsaeessneessseeeesaes 4-2 +Phe Console: Channel. 22. cscs ices svadesessahpscossteg egebseey ages ced evebsdes seete dns esehstnpsaubeted oses step pee 4-3 +MS-DOS ‘file names’.$3:.; ac.cseiyaieentiaelecnsie aie oui are ei ayia 4-3 +Floating point emulator .......... ce eeeeeeeeesseecsscecsseeceseeeesneecsaeecsseeceseecesseecsaeecseessneeeesaes 4-3 +Pate 80:s3isni this talest gain dain saad Palas ote Shaina osetia. 4-3 +Building the CLIB library and header objects ............eeeeeeseeseseeceseeeeeeeeesseeesaeesseeeees 4-4 +Cautionary Notes sssi.c.e i etiavien it ashe aoiaaiei ota bad ieee 4-4 + +5 Fundamental Programming Guide-lines ................cccssccssssseccsscssecssccecsssccecesseseesssccseesssceseeens 5-1 + +Tin tr OG UCHIOT os ek tes el iach i at wae cate cal ced ste cand eat see canned aenteat Si steee canta 5-1 +Other related docuMeNntatiOn.......... ee eeseeeseecsseecesceeesseecsseecseeceseeeesaeessaeesseeseneeessaes 5-1 +The source code for the examples ............eesceesecceseeeeseecseecsceseseeeesaeecsaeesseeesneeeesaes 5-2 +User Anterface:. sii 2isi8 thas ets as bee avis lensed Avid dau esi tvico bei esiteda teh 5-2 + +A first look at multiple event SOUTCES......... cee eeseeeseeesseeeesceceeseeesaeecsaeecsseecseecesaeeesaeecsaeers 5-3 +Remarks ‘On timers -.$:5. silts. oiel oo he Bled ea aed hie Band hao eetied 5-4 +Remarks: on ke ypresses's:J.c5:33 sasiesidecvtsteAisiasihas beth Naidesddtedevid aioe dei Aenea ha 5-4 +MO re Oi p1OWalt iss cos2o os sats Syceubsteus sab cdian cos vssisa Ans cous Avtsiba Aig eevadoreubs Ran eeiidawbonvs daads 5-4 +Status words: the other side Of P_lOWa€It oo... eee eeeeeeseeceseeceseeeeseecseecseeseseeeesaeessaeers 5-5 +Prioritisation Of CVENt SOULCES ........ eee eesecsseeesseeceseeeesseecsseecsseeceeeeesaeecsaeerseeesteeeesaes 5-5 +VO devices ii ceneralicss, ateissi assess cast eA sisesiostsse Sh ssaveisndeesbesed stestoseepoasivaeensseeressi ha 5-5 +The Console: device seccs2.es2.5 vege cuss sivedes Soves cuts Sesiel sake cavsebbesea savage cals cevaded Seats seitenusden Sinbely 5-6 +How to‘Canicel::a thers ch sisiss-stssiacdticeassstacdeeledesetaatageetds tess eataosendadeasteaiagendaieaetens 5-6 +Where to declare status WOrdS..........ccceescccseseessseecseecsneecsseecssaesesaeecsaeessaeeseeeessaeeesaes 5-7 + +A-first,look at ertorharidling 3: ).35c cenit dail endri ees eed e Baste 5-7 +Brror handling in Events cin: coiscsess.basi.5 cats toons tsdhah eeisduose 0s bi bevadeesecus ds nsvetevsrDuteseiee 5-7 +Fatal errors and non-fatal errors ..........eeeceeeseesseeesseecssceceececesaeeesaeecsaeessaeesseesssaeeesaes 5-8 +When resources need to be tidied explicitly... eeeccesneeesneeesneeseseeseseeeesaeessaeers 5-8 + +Inter-Process Communication: Events2 and Subproc.........eeeeeeeseesseeeeseeceseeeeseeeesaeeesaeers 5-8 +Acthird €vetit SOULCE ws c.65cistescd0s seuss eckeeebtee, Fei stvbs foibteestes stvie feb Tebslen sins Pevtdewsta ste de 5-8 +How Events2 passes data to SUDPI0C........ eee eeseeeeseeeeseeceseeeesaeeesaeecsaeecsaeessneesesaeeesaes 5-9 +The Code ti SUBProcis css sot cass cvs ssies Sab Lobe ewek Sheu pied Pedbewss Subd Lock Setacw es Seeeuoeh ocoenweh Sesooeh Senne 5-10 +Mechanisms for inter-process COMMUNICATION .......... eee eeeeeeseeeseeeeeeeeseeeeaeessaeesseeeees 5-10 +Debugging cooperating applications ........... cee eeeseecsseeeeseeeesseeesseecsaeecseecsseeeesaeeesaeers 5-11 +Error Handling im Bvents2.5:.235 hss stds hcenkictessedealetentigiagsotesisceeidatsosanaaieasieatiaesneanenyiass 5-11 +Socially responsible programming in Events2............:ecceesseeesseeeeseecsececeeeeeseeeeseeeesaes 5-11 + +Data received from:a-serial port s.s.s.5:.5 sts eiades his dacien aes eathisl asin An 5-11 +Opening the:serial: Port cssis: yess ochisek saves cash cieised Stees eavlevesselstese cas ieves ced sesesw eevee aeeei ss 5-12 +Active and inactive CVeNt SOUTCES 20... eeseeesseceseeeeseeeseeeesaeecsaeecsacecsseecseeeseeesnaeeesaes 5-12 +Debugging applications with serial COMMS ............:esecesseceeseeeeseeeseecsneeeeseeeesaeessaeers 5-13 +The tole:of: ptickles 2:8 wise aA inde iitha dade asada tshadea aes 5-13 + +Yielding CPU in compute-intensive programs ...........ssccseseeceseeceseceseeeeseeessaeecsaeessereeeenes 5-13 +Tdl@:ObjecCtss. 2: ssesisscsscaseesteaissectagusaasd ataceas deters ncaisenndaseadeenesaat daha Moeetes etenhda Goeetdaa st cat 5-14 +The meaning of calling p_1osignal......... ees eeeeeseecesneeeseeseeeesaeeceacecseeceseesseeseseeeesaes 5-14 +One drawback of COMtiINUOUS ACtIVILY ...... eee eee eeeeeeeseeceeeeseeeesaeeceaeecsseecetersneeeenaeeesaes 5-14 +Remarks On process PriOrities ........ ee eeseeeseecsseeeesceeesseecsaeecseeceseecesaeeesaeesseeesneeeesaes 5-14 +The-call p-tOvyieldissisiss. sdasscessashassadaseteatastasiostatess tan caseendateestentassenda seasteaiaveendateastgas 5-14 + +Gremeral Perm ark o.ii61. 255s scis sh nahh a oest iocs disk Bevdeed Se ckbvad pes cbeesied hisheoui se sheteh el ouboe sereh erent oe 5-16 +Multi-threadedness and multi-tasking... eee eeeesseeeseeeeseeeeseeeesseeseeeesaeessaeesseeeees 5-16 +Subprocess or 1dlé: Object? «1.5. isseeestais bi steviesevich eistest tc ata aeons bees 5-16 +Window redraws as an Vent SOUTCE....... ee eeesenecesneessneeseseeceseecsseecesaeessaecesseeesneeeesaes 5-16 +The APPMAN and ACTIVE classes in OLIB .0......ceseeeeceessecesseeceneecseeeeeseeeesaeessaeers 5-16 + + +CONTENTS + + +6 Copy-Protecting Softwar e...............scsscssccssscssssscssesssscscecssscesssscssesssscsssssscsscsssscssesssscssssssceseees On + + +Tin tO Ct Oni aps fos oe dees teg shoes eiestene tee stcga estes See sata ig stes ott slong esac seep tene eset deestene eats 6-1 +The freespace method s:.icisieiia ph eit ia. pei banning es 6-1 +First generation copying methods......... ec eeeeeseesscesssceesseecesseeesaeecsaeecseecsseecesaeeesaeeesaeers 6-2 +Preserving checksums :..3...2.:rvidiene aie kieran eh al nna eie 6-2 +What kind of change should be made «0.0.00... eeeeeeeeesseeeeseessnceceseeeesaeecsaeessaeesseeeesas 6-2 +Restricting the number of copies Made .......... ees eeseeeseeeeseceesseeesseecsseecsneeceseeeesaeessaeers 6-3 +Low level SSD information’, « o::.06. 22st. he oes eho hk ee oe dhe eel ae eh ad ae 6-3 +Copy-protection by changing the ROM 00.0... eescessecsseecsseeceseeeesaeeesaeecsaeecesaeeesaeessaeers 6-3 + + +7 Compatibility: sccsscssccccsscsecccssssescestcsnsacsesssaassssssssssosvensseseveasdsocvansdsdevansdsentancsesssadessnosesessosnstesueseeg dL + + +Initroduct On ¢::::.43. nA kee ius Lis Anh Aoh lhe Mon koh aah aae 7-1 +What machine am I running ON? ............ceeecceeessceceeseceeesseneecessaseecessneecensaneesessnsesessnsesenses 7-1 + + +iii + + +CHAPTER 1 + + +INSTALLATION + + +The Psion SIBO 'C' Software Development Kit (SDK) enables you to develop applications in 'C' for the +Psion SIBO family of hand-held and notebook computers: + + +e the HC range of corporate handheld computers +e the Series3 range of palmtop computers +e the MC range of laptop mobile computers. + + +The SDK is PC based - that is, you write and build your applications on a IBM PC or compatible and then +run (or debug) the application on a SIBO computer. + + +The SIBO SDK comes in three variants: Professional (Prof), Standard (Std), and Documentation (Doc). +The Prof and Std variants contain differing amounts of the TopSpeed C Package (produced by the Clarion +Software Corporation): + + +e the Prof variant contains the complete TopSpeed C Package +e the Std variant omits the TechKit and C Library Source Kit portions of the TopSpeed C Package. + + +Parts of the TopSpeed C Package are required in order to build any SIBO application. These are the parts +included in the Std variant of the SDK. + + +The TopSpeed C Package may be used independently of the SDK to write C programs to run on IBM PCs +and compatibles. + + +All three variants of the SDK contain the same three volumes of SDK documentation, comprising 14 +different manuals all told, together with associated software produced by Psion. This software +incorporates libraries, header files, auxiliary programming tools, example programs, and much more +besides. + + +Installation + +There are three phases to installing the SIBO SDK: +e installing the small code model of the TopSpeed C Package +e installing Psion software and example programs +¢ customising the TopSpeed system using special Psion files. + + +For information on installing the TopSpeed system, see the TopSpeed C documentation. (You may install +other code models as well as the small code model, but they will not be used by the SIBO SDK). + + +The Psion software consists of required parts and optional parts. For a full description of all the +available files, see the read.me files in the root directories on the supplied disks. + + +The files on the disks are in compressed ("zipped") form. The disks contain the pkzunzip program, which +can be used to decompress ("unzip") the other files as they are copied. + + +The installation procedure ensures that each group of files is copied to its correct directory. The read.me +files on the disks specify which files are present in each group. + + +GENERAL PROGRAMMING MANUAL + + +Directory structure +The TopSpeed software is usually located in a \fs\ directory tree. +The Sibosdk software is usually located in a \sibosdk\ directory tree. + + +There is no need for the \rs\ and \sibosdk\ directory trees to be on the same partition of your hard disk. Eg +the TopSpeed system could be on drive c:, with the Sibosdk system on drive d:. + + +Both the \ts\sys and \sibosdk\sys directories should be added to the MS-DOS path. Alternatively, you may +copy the contents of \sibosdk\sys (with the probable exception of the ts.red redirection file - see +Customising the redirection file below) to \ts\sys, in which case you will only need to add the \rs\sys +directory to the MS-DOS path. + + +Subdirectories under \sibosdk\ include: + + +lib the location of standard libraries, startup objects, and some loadable device drivers +(dynamic extensions to the SIBO operating system) + + +include the location of header files + +sys the location of the SIBO Debugger and other miscellaneous programming tools + +pr the location of some standard project files + +demo the location of various standard demo programs + +s3atool Series 3a versions of an icon editor and the Spy application + +STC (not present in all versions) the location of the source code for the Clib (standard C) +library + + +hwdemo (optionally) the location of programs demonstrating use of the HWIF library + + +hwifsre (optionally) the entire, buildable, source of the HWIF library, for interest and/or to allow +the writing of extensions to HWIF + +wd (optionally) the source printer scripts of some WDR printer driver files + +Idd (optionally) the source code of some example device devices + +hemast (optionally) software allowing alternative versions of the HC rom to be built + +wkdemo (optionally) source code of example software for the Workabout + +fconv (optionally) software allowing the creation of file format conversion DYLs for Word + + +oopdemo (optionally) the location of programs demonstrating the basic use of the Object Oriented +Programming system (other directories contain more advanced examples) + + +record (optionally) the source of the Object Oriented Series 3a Record application. This is +buildable, provided that the \sibosdk\oop directory has also been installed + + +The SIBO SDK requires between 3 and 6 Megabytes of disk space, depending on how much of it is +installed. + + +Reconfiguring the TopSpeed project system + + +The Sibosdk software contains files, including tsprj.txt and tsmain.txt, that are replacements for files of +the same name released by TopSpeed. The Sibosdk versions of the files allow the TopSpeed project system +to handle the Epoc 1Mc system type, and the Sibosdk tools generally, in addition to the systems normally +supported by TopSpeed. (See the following chapter for more details.) + + +The Sibosdk versions should be copied, from \sibosdk\sys, over the TopSpeed versions in \ts\sys (as guided +by read.me). Copies of the original TopSpeed files should be kept, with their extensions changed to .old + + +(say). + + +In case any specialised changes have already been applied to, say, your tsprj.txt and tsmain.txt files, you +should re-apply these changes to the Sibosdk versions. + + +1 INSTALLATION + + +In order for all these changes to have any effect, the TopSpeed tool tscfg has to be run: +type cd \ts\sys to enter the appropriate directory +type tscfg to invoke tscfg. + + +Note that the replacement files are not the same as those supplied with versions of the SDK earlier than +2.0. You must therefore repeat the reconfiguration process, even if you are upgrading from a previous +SDK version. + + +Customising the redirection file + + +The \sibosdk\sys directory contains the redirection file ts.red that allows the TopSpeed project system to +find the SIBO SDK header files, library files, and other required files. When you invoke the project +system to build an Epoc application it must be able to find this file. If there is no such file in the current +directory, the TopSpeed system looks for this file in the directory containing the TopSpeed software itself +(usually \ts\sys). So there are two options: + + +e overwrite the TopSpeed ts.red file (in the \ts\sys directory) with the Psion ts.red file (in the +\sibosdk\sys directory), and place a copy of the original TopSpeed ts.red file into the directory in +which you are writing PC C applications (if any) + + +¢ copy the Psion ts.red file into the directory in which you are writing a SIBO application. + + +The first option is more appropriate if you are writing more SIBO applications than PC applications, the +second if you are not. + + +The contents of the default ts.red file is basically as listed below. Again, note that the supplied file is +different from the ts.red in earlier versions of the SDK. + + +*.PR = .; C:\SIBOSDK\PR; + +* 7H = .; C:\SIBOSDK\INCLUDE; +*,HPP = .; C:\SIBOSDK\INCLUDE; +*,RH = .; C:\SIBOSDK\INCLUDE; +ta = .; C:\SIBOSDK\INCLUDE; +*.RG = .; C:\SIBOSDK\INCLUDE; +*.XG = .; C:\SIBOSDK\INCLUDE; +*.RSG = .; C:\SIBOSDK\INCLUDE; +* INC = .; C:\SIBOSDK\INCLUDE; +ee = .; C:\SIBOSDK\SRC; +*.CPP = .; C:\SIBOSDK\SRC; +*.CAT = .; C:\SIBOSDK\SRC; + +*.A = .; C:\SIBOSDK\SRC; +*.,OBJ = .; C:\SIBOSDK\LIB; + +* LIB = .; C:\SIBOSDK\LIB; + +* HLP = C:\TS\DOC; + + +For example, the meaning of the line +*.H = .; C:\SIBOSDK\INCLUDE; + + +is that any .h file referenced in the course of building an application should be searched for first in the +current directory, then in the c.\sibosdk\include directory. + + +To increase the search path for .h files, so that private .h files can be located from some other directory, +just edit the ts.red file so that the line becomes, for example: + + +baa! = .; ..\INCLUDE; C:\SIBOSDK\INCLUDE + + +Note that the contents of this file assume that you have installed the Sibosdk system on your c: drive. If +you have installed it on another drive you will have to edit ts.red to refer to the appropriate drive. + + +1-3 + + +GENERAL PROGRAMMING MANUAL + + +1-4 + + +CHAPTER 2 + + +A BRIEF OVERVIEW OF THE SIBO SDK + + +The SIBO SDK consists of a set of floppy disks containing the SDK software and a number of manuals +describing the software and the Psion SIBO family of mobile and hand-held computers. The floppy disks +contain the various tools, header files, libraries etc that are required to produce an image (img) file that +will run on Psion SIBO machines. + + +Manuals + + +The SDK manuals supplement the TopSpeed manuals. In particular you are referred to the TopSpeed C +Library reference for the description of standard C (CLIB) library functions. + + +The SDK contains the following manuals: + + +General Programming Manual + + +HC Programming Guide + + +Series 3/3a Programming Guide + + +Workabout Programming Guide + + +EPOC OSS System Services + + +Additional System Information + + +PLIB Reference + + +Window Server Reference + + +I/O Devices Reference + + +The SIBO Debugger + + +Hardware Reference + + +Programming in HWIF + + +This manual. It describes how to install the SDK, and how to +build an application that will run on the SIBO machines. It also +contains some notes on using the TopSpeed C Library reference +manual, some discussion on how to copy protect software for +SIBO computers, and a potentially very important chapter entitled +Fundamental Programming Guidelines. + + +Some documentation particularly oriented around the HC +computer range. + + +Some documentation particularly oriented around the Series 3 +range of machines. + + +Some documentation particularly oriented around the Workabout +computer. + + +Describes the software interrupt interface to the ROM-based +system services. An appendix contains a complete listing of the +EPOC service numbers. This will be of particular use to OPL and +assembly language programmers who wish to make direct access +to EPOC services. + + +Describes the MCLink communications software, resource files, +WDR printing, various file formats, how to write device drivers, +and other miscellaneous topics. + + +Describes the Psion PLIB library (this library provides the most +direct access to the ROM based system services). + + +Describes the window server library WLIB which implements a +range of sophisticated graphics operations. + + +Describes the interface to some of the Epoc device drivers, +including those which access the serial and parallel ports. + + +Describes how to use the SIBO Debugger to debug applications +being developed for SIBO computers. + + +Describes the basic hardware of SIBO computers. + + +Describes the HWIF library (which contains support - mainly for +the Series3 - for menus, dialogs, editors, and printing). + + +2-1 + + +GENERAL PROGRAMMING MANUAL + + +Object Oriented Programming Describes the development of applications using Object Oriented + +Guide techniques. Its introduction provides an overview of Psion's +Object Oriented programming system and of the OLIB, HWIM, +FORM and XADD object libraries. + + +ISAM Reference Describes the ISAM dynamic library which provides Indexed +Sequential Access management for large database files. + +OLIB Reference Describes the OLIB object library. + +FORM Reference Describes the FORM object library. + +HWIM Reference Describes the HWIM object library. + +XADD Reference Describes the XADD object library. + + +Where to start + + +There is a very large amount of information in these manuals - perhaps too much for any one person to +keep it all in their head. However, few developers will need to make detailed reference to more than +around half of the manuals. + + +The manuals contain many cross references to sections where various topics are discussed in more detail. +Use these cross references to help you find your way around the SDK documentation. The chapter +immediately after this one is probably the best place to start. Alternatively, start reading the HC +Programming Guide, the Series 3/3a Programming Guide, the Object Oriented Programming Guide, the +Plib Reference manual - or anything that catches your eye as you flick through the pages. + + +The terms SIBO and EPOC explained + + +A SIBO machine is a battery-powered portable computer that is based on the SIBO architecture. This +architecture is designed to minimise the size, weight and power consumption of the computer. The key +components of the architecture are: + + +e A sophisticated power management system that selectively powers subsystems under software +control + + +e Solid State Disks (SSDs) that provide fast low-power silicon-based mass storage with no moving +parts + + +e Asynchronous serial interface for peripherals running at high speed (Mega bit rates) +e An 8086 class of processor (or any compatible processor such as an 80286) + + +e Hardware protection of the system from aberrant processes (address trapping of out-of-range +writes and a watch-dog timer on interrupts being disabled) + + +e = Real-time clock + +e ROM-resident system software + +e Graphics LCD display + +e A touch sensitive digitising pad that provides a pointing device (used in some models) +e ISDN combo sound system (used in some models). + + +The hardware architecture is primarily implemented in custom ICs called ASICs. The SIBO architecture +uses surface-mounted static CMOS ICs throughout. For further information see the Hardware Reference +manual. + + +The EPOC operating system, designed for the SIBO architecture, has the following features: +e preemptive multi-tasking +e MS-DOS-compatible file systems +e installable file systems, including remote file access +e asynchronous services + + +e support for client-server architectures (used to implement system components such as the file +server and window server) + + +2 A BRIEF OVERVIEW OF THE SIBO SDK + + +¢ acomprehensive I/O system with many built-in I/O devices + +e dynamically loadable device drivers + +e reentrant function library + +e multiple processes of the same program share a single copy of the code +e support for object-oriented programming + +e code-shared dynamic link libraries. + + +On SIBO machines, the system software resides on an in-built ROM. A version of the EPOC operating +system also runs on a PC. + + +See the Plib Reference manual for more details. + + +Fatal programming errors (Panics) + + +When the system detects a condition that it believes could only arise from a bug in a the application +program, the system terminates the process with a "panic number" in the range 0 to 255 inclusive (where +the system is said to "panic the process"). A panic is a fatal exception that causes the process to terminate +immediately. There is no way for applications to avoid being terminated when a panic has been started. + + +As well as protecting the system from defective applications, the panic system enforces a greater discipline +on application code by terminating a process as soon as the condition is detected. + + +Panic numbers + + +Programming errors detected within different areas of the system code give rise to different panic +numbers. The following table lists the possible panic numbers and the corresponding system code that can +give rise to them. + + +0 to 80, and 255 The PLIB library +81 to 129 The Window Server library +130 to 160 The OLIB object library +These panic numbers are described in more detail in the appropriate manuals. + + +Panic numbers in the range 160 to 254 are used by code that is not resident in the ROM (such as the +ISAM library). A given panic number may be used by more than one piece of code; such a panic may +therefore have one of a number of causes. The only definitive way to discover the origin of such a panic is +to make use of the SIBO Debugger to catch the panic and then trace it back to its source. + + +C++ and Object Oriented programming + + +This version of the SDK is compatible with TopSpeed C++ although, at the time of writing, the TopSpeed +C++ package is not supplied by Psion as part of any variant of the SDK. + + +Note that the kinds of classes, and the means of creating and accessing them, in C++ are quite different +from those in the Psion Object Oriented programming system. + + +Regardless of whether you use C or C++ to develop Object Oriented applications, if you wish to use Psion +objects you must create instances of them and send messages to them by the mechanisms that are +described in the Object Oriented Programming chapter of the PLIB Reference manual and the Object +Oriented Programming Guide. + + +If you intend to develop a SIBO application that uses only Psion objects, you may still use C++ as a +"better" version of C, without making use of its Object Oriented aspects. + + +You may, if you wish, use a mix of Psion and C++ classes, provided you make sure that you create and use +instances of classes of each kind by the appropriate means. It is quite acceptable, for example, to use Psion +classes for the application manager and user interface, but use C++ classes in the 'engine’ of an +application. + + +GENERAL PROGRAMMING MANUAL + + +2-4 + + +CHAPTER 3 + + +BUILDING AN APPLICATION + + +Introduction + + +The end result of developing a program to run on a SIBO computer is normally an image program, with +characteristic extension .img. Essentially, .img files are to Epoc what .exe files are to MS-DOS. +(Sometimes, the image file is given the extension .app instead. See later for the distinction between .img +and .app forms of images.) + + +Image files are actually produced via an intermediary .exe file by the operation of a tool emake.exe, +though in practice this process is automated on behalf of the developer. The point is that the development +cycle for .img files is basically the same as for .exe files in more traditional programming environments. +The same compile-link-debug cycle exists in both cases. + + +The program is written, compiled, and linked on the PC. These steps involve the TopSpeed compiler and +linker, and TopSpeed project (.pr) files. These steps may also involve the full TopSpeed ts development +environment, which is an Integrated Development Environment (IDE). Alternatively, developers may +prefer a more traditional approach, involving their own favoured stand-alone text editor, and a batch-file +mechanism for invoking the TopSpeed compiler and linker. + + +Once linked, the program is transferred to the SIBO computer in one of three ways: +e under the control of the SIBO Debugger +e via a SSD written to by a PC SSD drive and then placed into the SIBO computer +e via a serial link, using Comms software such as MCLink. + + +A program running on a SIBO computer (though not one in its rom) can be debugged under the control of +the SIBO Debugger running on a PC. If the program has been built under special conditions, source level +debugging will be available; otherwise just machine-code level debugging. + + +The remainder of this chapter gives more details on all the above points: + + +e it introduces some particularly relevant aspects of the TopSpeed project file system +e it describes some batch files that may be found useful when building applications + + +e several example applications demonstrate the points made (all the example applications and +associated files referred to in this chapter are optionally copied into \sibosdk\demo when the SDK +is installed) + + +Equipment required +The following equipment is required in order to create an application that runs on a SIBO computer: +e One target SIBO computer (HC, MC, or Series3) +e One PC +e The TopSpeed C development system on the PC +e The Psion SIBO SDK software on the PC + + +e One or other form of communication between the HC and the PC. + + +3-1 + + +GENERAL PROGRAMMING MANUAL + + +Around 5 to 7 Mbytes of PC hard disk is required to install the TopSpeed C development system and the +Psion SIBO SDK software. There is no particular requirement for the PC to have extended memory. +Development can take place on an XT, but a 486 machine with around 4 Mbytes of extended memory +machine will obviously produce results more quickly. + + +Which files are needed +To build an application, the following files are required: +e source files, such as .c and .h files +e aproject file, with extension .pr +e aredirection file, with name ts.red +e libraries, with extension .lib. +At the same time, various batch files (extension .bat) may be found useful. + + +Additional files may be required for the development of applications with the aid of the Object Oriented +system - see the Object Oriented Programming Guide for further details. + + +There is no need to have a separate project file or redirection file for every single application. For +example, ordinarily there will only be one redirection file on any one PC, shared between all applications +written on that PC. One possible exception is in the case of developers who use the TopSpeed system to +write PC programs as well as SIBO programs. + + +A first example application + + +The following discussion centres around a very simple "Hello World" program. +The source C code is as follows: + + +/* +HELLO.C + + +CLIB Hello World application +bai A + + +#include + + +int main(VOID) +{ +printf ("Hello World"); +getchar(); +return (0); + + +} + + +Evidently, the program prints the message Hello World onto the screen, waits for the ENTER key to be +pressed, and then terminates. + + +A first look at project files + + +Before hello.c can be compiled and linked, a project file needs to be specified. In this case, the following +(hello.pr) suffices: + + +#system epoc img +#model small jpi + + +#compile hello +#link hello + + +The meanings of the last two lines of this file are obvious enough: the file hello.c should be compiled, and +then the resultant object file linked to create hello.img. Note that in any case of ambiguity, the extension .c +should be added to the name specified in the #compile statement. + + +3-2 + + +3 BUILDING AN APPLICATION + + +The first two lines in hello.pr are less obvious. Their meanings are as follows: + + +#system epoc img The end outcome of the build is a .img file, as defined in the Epoc-customised +part of the TopSpeed configuration (alternative #systems include dos and win) + + +#model small jpi The code is to be compiled in small model (code and data segments each +restricted to 64K), with the jpi (TopSpeed C) convention of using registers to +pass parameters to subroutines. + + +These two lines must be present in all project files used to build applications for SIBO computers. +Other possible contents of .pr project files are discussed later in this chapter. + + +Creating the .img file + + +There are two ways a .pr file can be used to create a .img program: +e inside the TopSpeed ts programming environment (see TopSpeed documentation for full details) +¢ outside the ts environment. + + +For example, one reason for working outside the ts environment would be to allow the use of another text +editor, such as Brief. + + +The remainder of this programming manual describes use of .pr files outside of the ts environment. +For the moment, simply type: + +tsc /m hello +to have hello.c compiled and linked, with the end result (among other files) being hello.img. + + +The significance of the /m parameter is that the project file is executed in "make" mode, with files not +being recompiled or relinked needlessly. + + +Copying the program to the target machine + + +If your PC has a set of SSD drives attached, simply copy hello.img onto an SSD in one of these drives, +and then insert the SSD into the target machine (the SIBO computer). Otherwise, you may wish to use +MCLink as follows: + + +¢ connect the SIBO computer to your PC using a suitable cable + + +e run the Link application on the target machine (type 1ink at the HC command line, click on the +Link icon on an MC, or set Remote Link on in the System Screen of a Series3) + + +e run MCLink on the PC (eg by typing mcurnx if \sibosdk\sys is on your path) +e adjust the MCLink serial port and baud rate parameters if required + + +e type copy hello.img rem::m:\hello.img to transfer the program to the m: drive of the remote +machine (or copy the file to rem: :m:\img\hello.img on a Series3) + + +For more details about the MCLink program, see the chapter Mclink, Mcprint, and Slink in the Additional +System Information manual. (For example, that chapter explains how the whole process of running +MCLink can be handled via time-saving batch files at the PC end of the connection.) Finally, another +way the program can be transferred from the PC to the target computer is by using the SIBO Debugger, as +discussed below. + + +Running the program on the target computer + + +The way the program is run on the target computer varies from computer to computer: +e onan HC, simply type hello at the s prompt of the Command Shell +e onan MC, use the Run menu command of the System application, and select hello.img + + +¢ ona Series 3 or Series 3a, the entry Hello will appear in the file list of the RunImg application +when this list is next updated (assuming that hello.img has been copied into a \img\ top-level +directory), so that hello.img can be run simply by positioning the highlight over Hello and +pressing ENTER. + + +3-3 + + +GENERAL PROGRAMMING MANUAL + + +Stepping through the program with the SIBO Debugger +In order to debug a program, there is no special need to copy it "by hand" onto the target machine. +Just type + +\sibosdk\sys\sdbg hello + + +(or equivalent) at the PC end, and ensure Link is running on the target computer. (These instructions +assume that hello.img is in the current directory on the PC.) In due course, the debugging screen will +appear on the PC. (When debugging a program running on an MC, the baud rate for the Debugger to use +may have to be given explicitly - eg \sibosdk\sys\sdbg -b19200 hello.) + + +Step through the program (use F8 or ALT+S) until it hangs (waiting for a key to be pressed on the target +computer). Or simply run the program to completion (use F9 or ALT+R). + + +In fact, if hello.img has been built as specified above, the debugging screen will come up in machine code +level. In order to debug at the source code level, a slight change has to be made in the way hello.img is +built: + + +e = either a line #pragma debug (vid=>full) has to be inserted in the project file (before any +instruction to #compile) + + +e alternatively, a parameter /v2 can be added to the command line invoking the project file. +Thus typing + +tsc /m hello /v2 +at the PC command line builds a version of hello.img suitable for source level debugging. +As before, just type + +\sibosdk\sys\sdbg hello + + +but this time, the debugging screen by default starts in source level mode, and supports inspection of +variables, etc. See the SIBO Debugger manual for more details. + + +A PLIB version of Hello World + + +PLIB and CLIB contrasted +The above "Hello World" program uses the so-called CLIB library. + + +CLIB is a version of the TopSpeed C library for the EPOC operating system. As such, it is a version of the +standard ANSI C library. The functions in CLIB are described in the TopSpeed C Library Reference +manual. Additional notes, including a list of the TopSpeed C library functions that are not implemented, +may be found in the following chapter, Notes on Clib. + + +The EPOC version of the TopSpeed C library supports the ANSI functions and most of the portable +functions that are commonly supported by MS-DOS C libraries such as Microsoft C and Borland's Turbo +C. The less portable functions such as those that access the BIOS and graphics functions are not included. + + +The benefits of using CLIB are: + + +e portability (existing C programs can easily be converted) + + +e less to learn for programmers already familiar with standard C libraries. + + +However, for many programs, developers are strongly urged to consider using not CLIB but PLIB - Psion's +proprietary C library. Whilst PLIB differs from the ANSI standard in many places, there are good reasons +for all these differences, so as to best take advantage of the Epoc architecture. In particular: + + +e many of the ROM-based EPOC system services are not available from CLIB (eg asynchronous +I/O, inter-process messaging, the window server graphics functions) + + +e executables are larger in CLIB and the process takes a larger data segment. + + +The executables are larger because, although CLIB uses the ROM-based system services wherever +possible, it is still a much "thicker" library than PLIB. The data segments also tend to be larger because +the various CLIB subsystems typically require large static buffers and tables. + + +3-4 + + +3 BUILDING AN APPLICATION + + +See the Introduction chapter of the PLIB Reference manual for more details. + + +In fact, unless you are using the in-built user interface object dynamic libraries (accessed using object- +oriented programming), you can freely mix PLIB calls with CLIB. Experienced C programmers can, if +they wish, initially use the more familiar CLIB functions and regard PLIB and WLIB (the window server +library) as they would regard non-portable components of any C library. + + +It is worth converting completely to PLIB and WLIB when the desirability of making efficient use of +memory outweighs the benefits of portability and familiarity. + + +The code for p_hello.c + + +The code for a PLIB version of the above program hello.c is contained in the file p_hello.c: + + +/* +P_HELLO.C + + +PLIB Hello World application +ef + + +#include + + +GLDEF_C INT main(VOID) +{ +p_printf ("Hello World"); +p_getch(); +return (0); + + +} +and a corresponding project file p_hello.pr would be + + +#system epoc img +#set epocinit=iplib +#model small jpi + + +#compile p_hello +#link p_hello + + +The following differences will be noticed between hello and p_hello: +e the PLIB program uses a Psion-proprietary header file (plib.h in this case) +e the PLIB program uses Psion-proprietary function calls (p_xxx functions) + + +e the PLIB program links with a different library (this is one effect of the epocinit line in the +project file - discussed further below). + + +To build p_hello.img, just type either tsc /m p_hello Of tsc /m p_hello /v2 (the latter producing a +version supporting source-code debugging). + + +As a result of the differences between hello and p_hello, a substantially smaller .img file is produced (try it +and see). + + +The reason for the remarkable codesize improvement of the PLIB program is that, as mentioned earlier, +the functions in the PLIB library provide only very thin shells over functionality that is present in the +ROM of the SIBO computer. PLIB programs make better use of the SIBO ROM software than do CLIB +programs. Being tailored to the particular needs of SIBO computers, PLIB evolved with very different +constraints and objectives from standard C libraries. In many cases, PLIB functions can be claimed to +"improve" upon the specification of their nearest CLIB equivalents. + + +The difference in size between CLIB and PLIB programs is not always so remarkable as in the above +example - it depends on the number and types of library function calls made. Indeed, it is perfectly +possible to write some parts of an application using CLIB, and others in PLIB. This fact considerably +simplifies any process of converting a previous large programming project from one computer system to +the SIBO SDK system. + + +Whilst it is possible to avoid PLIB entirely, this is not recommended. Time spent gaining familiarity with +the functions in the PLIB library should prove an excellent investment, aiding the production of leaner +and more powerful applications. In any case, familiarity with PLIB is a pre-requisite for accessing many +other parts of the SIBO ROM software - such as the enhanced graphics facilities of the Window Server. + + +3-5 + + +GENERAL PROGRAMMING MANUAL + + +The epocinit statement in .pr files +In p_hello.pr, the command +#set epocinit=iplib + + +sets the value of the project macro %epocinit. Note that this command must precede the #mode1 command +in any .pr file. + + +This command serves two purposes: it specifies whether you are using the CLIB or PLIB startup object +files, and it specifies the stack size for the .img file produced. The allowed values of sepocinit are: + + +iclib CLIB startup, 8k stack (recommended size when using CLIB startup) +iclib4 CLIB startup, 4k stack +iclib2 CLIB startup, 2k stack +iplib PLIB startup, 4k stack (recommended size when using PLIB startup) +iplib8 PLIB startup, 8k stack +iplib2 PLIB startup, 2k stack + + +If sepocinit is not set then it defaults to iclib (as in hello.pr). + + +You must use the CLIB startup object files if you are writing a program that includes any CLIB library I/O +functions. It is, however, possible to use many CLIB library functions (for example, the memory allocation +functions) in conjunction with the PLIB startup. If you do not use any CLIB library functions then you +should always use the PLIB startup. + + +See the Introduction chapter in the PLIB Reference manual for more about startup object files. + + +Housekeeping batch files and re-using project files + + +A general project file: unnamed.pr + + +Clearly, a project file such as p_hello.pr can be used, with only nominal changes, for a wide range of other +similar programs. + + +Consider the related project file, unnamed.pr: + + +#system epoc img +#set epocinit=iplib +#model small jpi +#compile %main +#link %Smain + + +in which the only difference from p_hello.pr is that references to p_hello have changed into main. +Any batch file that invokes unnamed.pr has to set the value of smain as a parameter to tsc. For example, + + +tsc /m unnamed.pr /smain=%1 + + +with the TopSpeed /s construct being used to set the value of main to the variable passed into the batch +file. + + +A batch file for test compilation + + +A programmers’ text editor usually has some means to compile or "test compile" a source file, from inside +the editor. Many programmers find this a considerable boost to productivity. + + +For example, Brief supports compilation on the ALT-F10 hot key, with the way the compilation is done +being determined by an MS-DOS environment variable: + + +e = during autoexec.bat (or a batch file called therein), set the value of bcc, eg to !"cc.bat %s" + + +e the effect of ALT-F10 while editing a .c file would then be to run the batch file cc.bat, passing the +basic name of the file (ie less the path and extension) into the batch file + + +e the leading exclamation mark specifies that compiler warnings should be reported, as well as +errors. + + +3-6 + + +3 BUILDING AN APPLICATION + + +The TopSpeed ts integrated development environment naturally possesses an equivalent mechanism, but +some users may prefer to use an independent text editor. + + +Accordingly, one suggestion is that there should be a file cc.bat in the local directory (or in the path), with +the following contents (or equivalent): + + +tsc %1.c /fpunnamed + + +The meaning of the /fp construct is that the specified project file should be used (in this case, +unnamed.pr). + + +Given that there is no /m in this command (nor any /1), the specified project file is invoked in so-called +"compile" mode: nominated files are compiled, without any files being linked. Further, the compilation +always takes place, without any calculation of whether an object file is already "up-to-date". + + +Once all the required C source files in a project have been successfully compiled, the programmer can exit +the editor, and then "make" the project in the normal way: + + +e no time will be wasted in recompiling files unnecessarily +e a.img file will be produced (if the make is successful). + + +The cc. bat file used for test compilation could be accompanied by a make.bat file that invokes the project +file in "make" mode. + + +Some complications + + +There are a couple of shortcomings with the above batch file cc. bat: +e it takes no account of whether files should be compiled with full debug information +¢ it takes no account of a possible specialised .pr file: the project file unnamed.pr is hard-wired. + + +It does not take too much imagination to come up with a more general scheme - as is embodied in the +batch files cc.bat and make.bat actually shipped with the demo files p_hello.c etc: + + +e atest should be made for the existence of a project file with name 31. pr + + +e attention should be paid to the value of an environment variable for whether to generate full +debugging information. + + +The batch files supplied assume that the required debug status is stored in an environment variable +%4pivids. This should have one of the values v2 (for full debug information) or vo (for no debug +information). However, cc.bat and make.bat each call a subsidiary batch file, checkvid.bat, which ensures +that %jpivias does indeed exist and has one of these values. + + +The value of s jpivids is itself expected to be set up by calling the final batch file in the suite: vid.bat. +Typing + + +vid on +at the MS-DOS command line has the effect of setting sjpivids to v2, whereas typing +vid off + + +sets $jpivids to vo. Typing via by itself echoes the current vid setting. + + +3-7 + + +GENERAL PROGRAMMING MANUAL + + +The contents of these four batch files are as follows: + + +(vid.bat) + + +@echo off + +goto X%1X + +:Xv0X + +:Xoff£X + +set jpivid=v0 +echo VID is now OFF +goto :end + +:Xv2X + +:XonX + +set jpivid=v2 +echo VID is now ON +goto :end + +2XX + +call checkvid +goto Sjpivid% +:v0 + +echo VID is OFF +goto end + +:v2 + +echo VID is ON +send + + +(checkvid.bat) + + +@if not "Sjpivids"=="v2" set jpivid=v0 +(co batt) +@echo off + + +call checkvid + +if exist %1.pr goto custom +tsc %1.c /fpunnamed /%jpivids +goto end + +:custom + +tsc %l.c /fp%1 /%jpivids + +send + + +(make.bat:) + + +@echo off + +call checkvid + +if exist %1.pr goto custom + +tsc /m unnamed.pr /smain=%1 /%jpivid% + + +goto end + +:custom + +tse /m %1.pr /smain=%1 /%jpivid% +send + + +Naturally, there is considerable scope for further personalisation and enhancement of these batch files, if +desired. + + +One final refinement would be to use the MS-DOS prompt command to change the prompt to reflect the +current value of vid. For example, + + +prompt $p_%jpivid%s$sg + + +(The reason it is generally important to keep track of whether full debugging information is being +generated is that significantly larger .img programs can result in this case.) + + +TSC versus TSCX + + +All the examples of compiling and linking that have been given so far use the TopSpeed tsc command. +This command does not make use of expanded memory and may cause problems, particularly when +linking large applications. + + +Most of the batch files supplied with the SDK to compile, link or make executables use the tsc version. If +this causes difficulties on your PC, you may find that replacing tsc with tscx (which uses expanded +memory) in these batch files will cure the problem. + + +3-8 + + +3 BUILDING AN APPLICATION + + +More complicated programming setups + + +The remainder of this chapter makes no mention of programming technique or programming concepts +within the SIBO SDK system (see the later chapter Fundamental Programming Guidelines for that). +Rather, it continues to explain more details of the mechanics of building applications of various sorts. + + +Simple PLIB examples + + +The following four programs all use the default project file, unnamed.pr, and each consist of only one +source module: + + +p_search searches a specified text file for a given piece of text +p_prndir prints specified directory listings to the screen + +p_dlist lists all current "devices" (ie local and remote disk drives) +Pp_comp compares two specified files, to see if they match. + + +For example, to build a version of p_dlist.img suitable for source-level debugging, just type + + +vid on +make p_dlist + + +To exit any of these programs which repeatedly request user input, simply press ENTER on an empty +input line. + + +Note: these programs are all restricted to so-called console i/o: +e no attractive graphics +e limited support for the user editing data entered previously. + + +Additionally, they pay no attention to the actual size of the screen on individual SIBO computers. Whilst +the data they display fits well enough on the large screen of MC computers, the display is less suited to the +smaller screens of HC or Series3 computers. Simple modifications can make amends in this last regard. +But for enhanced graphics output, use of Window Server functions is needed. + + +Finally, these programs are all single-threaded, ie each has only one event source (the keyboard). At the +same time, they contain no asynchronous i/o. (The vital topics of multi-threaded programming and +asynchronous i/o are two of the central themes of the chapter Fundamental Programming Guidelines.) + + +But despite their limitations, these four programs will hopefully be found useful for the purpose of +acquiring familiarity with .pr project files and with the SIBO SDK system generally. There is no need to +worry unduly over their detailed content; however, taking the time to build them and then improve them +could well turn out a very rewarding exercise (eg in making the transition from CLIB to PLIB). + + +Multi-file programs +For a program with more than one source file, the corresponding .pr needs but a slight modification. + + +For example, suppose a program triple has three source files: triple.c itself, utils].c and utils2.c. A +suitable project file triple.pr would be + + +system epoc img +set epocinit=iplib +model small jpi + + +compile triple +compile utils1l +compile utils2 + + +link triple +The effect of the final #1ink statement is actually as follows: +e link together all the files listed with #compile statements + + +e link also the relevant startup module and standard libraries + + +3-9 + + +GENERAL PROGRAMMING MANUAL + + +e link also any object files or libraries specified by any #pragma link statements (see below for +examples) + + +e give the final executable the name specified in the #1ink statement. + + +Note in particular there is no need for the name specified by the #1ink statement to match the name of the +.pr file, nor the name of any of the individual files linked together. + + +Graphics programs + + +Programs which interact directly with the Window Server can produce a large variety of impressive +graphics effects - icons and bitmaps, shapes and areas, mixed fonts and styles, scrolling and animation, +information messages and alerts, and so on. + + +These programs can operate with .pr files of exactly the same form as described earlier in this chapter. For +example, the file unnamed.pr can continue to be used, unchanged, for any simple single-module Window +Server program. Parts of the Window Server library, wlib.lib, are automatically linked in as required, +without any change being required in the .pr file: there is no need to ask for wlib.lib explicitly. + + +The source modules will, of course, have to change in the following aspects: +e calls to Window Server functions gxxx or wxxx will be included +e the Window Server header file wlib.h will have to be #included. + + +For more details, including some introductory Window Server programs of the "Hello World" variety, see +the Window Server Reference manual. + + +HWIF programs + + +Developers writing for the Series3 can take advantage of the additional menu and dialog functionality +(amongst other features) of the HWIF library, to create applications very similar to those built into the rom +of the Series3. + + +See the Programming in HWIF manual for full details, including a suite of example programs. +Project files for these programs need to include the line + +#pragma link (hwif.lib) +since the HWIF library is not one of those that are automatically searched at link time. + + +Customised libraries + + +Developers may wish to collect various utility routines, or other subsets of code, into their own libraries, +which can in due course be linked into different programs. Possibly, developers may wish to distribute +their libraries in object form (./ib files), and not in source form. In such a case, there is likely to be at least +two different .pr files: one controlling the creation of the .lib file, and one that, later, joins the ./ib file into +a required application program. + + +For example, suppose that modules utils/.c and utils2.c are to be compiled and linked into a library called +utils.lib. This can be accomplished by means of the following project file: + + +#system epoc img +#set epocinit=iplib +#model small jpi +#compile utilsl +#compile utils2 +#dolink utils.lib + + +Note the following points: + + +e the command #dolink is used rather than #1ink, to stop the TopSpeed system attempting to link +in a startup object too (not to mention other standard libraries) + + +e the extension .1ib explicitly given overrides the default .img that would otherwise be assumed +on account of the statement #system epoc img. + + +3-10 + + +3 BUILDING AN APPLICATION + + +A project file to produce an application tutils, say, that made use of functionality in utils.lib, could then be +as follows: + + +#system epoc img + +#set epocinit=iplib +#model small jpi +#compile tutils +#pragma link (utils.1lib) +#link tutils + + +with utils.lib being searched for along the path specified in the redirection file ts.red. + + +Applications containing assembler as well as C + + +In principle, it is perfectly possible for an application to include assembler source modules, as well as +modules written in C. + + +For example, if an application contains two source files, cfile.c written in C and afile.a written in +assembler, the following could appear in the project file: + + +#compile cfile +#compile afile + + +The TopSpeed system will automatically run the appropriate "compiler" for each specified type of file - ie +compiling the .c file and assembling the .a file. + + +However, programmers should note that there are various rules that must be adhered to in writing +assembler modules for Epoc programs. See the /ntroduction chapter of the PLIB Reference manual in the +first instance. + + +Note: the TopSpeed system will give an error message, and terminate, if there are two possible files each +candidates as the source for of a #compile statement - for example, if the files cfile.a and cfile.c both exist +in a directory. As another example, if a directory contains files query.c and query.rc, the statement +#compile query will again result in an error - since the TopSpeed system regards the .rc file as a possible +source file too. All these cases can be circumvented by giving the extension explicitly in the #command +statement - eg #compile query.c. + + +Other advanced use of the project file system + + +The TopSpeed documentation describes many possible ways to exercise further control over the process of +building program files. + + +One general piece of advice should, however, be borne in mind: while learning to program within the +SIBO SDK system, please accept the default configuration proposed by Psion. Only attempt to refine this +configuration once your program is already clearly working. Otherwise, it may prove difficult to determine +whether some unexpected program behaviour is due to a coding mistake, or to some unexpected side- +effect of a proposed "optimisation" of the build configuration. + + +In any case, optimisations resulting from careful choices of PLIB or WLIB (etc) functions, are likely to +prove more significant than any that can easily be achieved by tweaking the SIBO version of the +TopSpeed build configuration. + + +It is also generally a bad idea to ignore warnings from the compiler and linker (except where explicitly +mentioned in the SDK manuals). Rather than discounting these warnings as "quirks" of the system, they +should all be analysed and dealt with. In particular, don't be too hasty to disable "inconvenient" compiler +warnings. + + +Note that the SIBO SDK build configuration is actually defined in two different parts: +e in the file tsprj.txt which has to be "compiled" (using tscfg) before being used +e in the file stdepoc.h which is always the first include file in any source module. + + +As mentioned in the chapter on /nstallation, the file tsprj.txt released as part of the SIBO SDK modifies +and extends the one released by Clarion themselves, by adding in details specific to the SIBO SDK +system. + + +GENERAL PROGRAMMING MANUAL + + +Greater control over the image file created + + +This section explains some of the SIBO add-ons to the TopSpeed project file build system. It also covers +standalone use of the tools edump.exe, emake.exe and eremake.exe: + +e edump.exe provides key information about the contents of an image file + +e emake.exe is the underlying tool which creates image files + +e eremake.exe can be used to alter some of the "additional" contents of image files. + + +Priority, minimum heap, and version number + + +Three project file variables can be used to override various defaults otherwise used when a .img file is +created: + + +sversion sets the version number of the .img file, which otherwise defaults to 0x100f + +spriority sets the initial priority of the program, which otherwise defaults to 0x80 + +sheapsize sets the initial and minimum heap of the application, which otherwise defaults +to 0x80. + + +The application version number can be read by various pieces of software, for example the Application +Info command of the System application on MC computers. For more about legal version numbers, see the +section on p_version in the PLIB Reference manual. + + +The initial process priority may occasionally need to be specified explicitly, eg for an application that is +part of a suite of cooperating applications. See the section on p_setpri in the PLIB Reference manual and +also the section Priority changing in the chapter General Window Server Functions in the Window Server +Reference manual. + + +The value of sheapsize is the one that applications are most likely to wish to alter, since this has +significance for error handling (see the chapter Fundamental Programming Guidelines later in this +manual): + + +e the value of sheapsize is in paragraphs, eg 0x80 means 0x800 bytes ie 2 Kbytes + + +e the operating system will refuse to start an instance of the application if this amount of free heap +space cannot be found for it + + +e once started, the application will never have its heap shrunk below this value. +The default values for these variables can be overridden in either of two ways: +e aline such as #set heapsize=0x180 can be added into the project file + + +e the parameter /sheapsize=0x180 can be added to the end of the tsc command invoking the +project file (this is evidently the same syntax as in the /smain=%1 in the supplied batch file +make.bat). + + +Use of edump.exe + + +The tool edump.exe can be used to verify the values of the above three variables (amongst others) for a +specified .img file. For example, typing edump p_hello results in output such as + + +EDump V2.02F (03/10/90) Copyright (C) Psion PLC 1989 +LOC: :D:\SIBOSDK\DEMO\P_HELLO.IMG IMAGE file data + + +Image version = 200F + +Code Segment = 01D0 (bytes) +Initial IP = 0000 + +Stack = 1000 (bytes) +Data = 0040 (bytes) +Heap = 0800 (bytes) +Data Segment = 1840 (bytes) +Initialized data = 0030 (bytes) +Code checksum = DA14 + +Data checksum = OBF7 + +Code Version = 100F +Priority = 0080 + +Header size = 0040 (bytes) +Dyl count = 0000 + +Dyl table offset = 00000000 +Image file size = 00000240 (bytes) + + +where the default values of "Heap", "Code version", and "Priority" can all be seen. + + +3-12 + + +3 BUILDING AN APPLICATION + + +Deleting p_hello.img and rebuilding it via the command +tsc /m p_hello /sversion=0x110b +before running edump again yields identical output, except that the "Code version" line changes. + + +Differences between .app files and .img files + + +Strictly speaking, there is no real difference between image files with extension .img and those with +extension .app. For example, although the System applications on the MC and on the Series3 usually +expect to install .app files, they 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 (only for Series3 applications). + + +As such, a .app file is simply a .img file which has some associated files conveniently built into it. A +significant advantage of a .app file is that a user cannot inadvertently sabotage the operation of the +program by copying the .img file itself from one drive to another, but neglecting to copy one of the +associated files. + + +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 (though no such renaming takes place automatically). + + +The inclusion of these embedded files can be confirmed by running the tool edump.exe as follows. Typing +edump tele.app might yield + + +EDump V2.02F (03/10/90) Copyright (C) Psion PLC 1989 +LOC: :E:\SIBOSDK\HWDEMO\TELE.APP IMAGE file data + + +Image version = 200F + +Code Segment = 1EDO (bytes) + +Initial IP = 0000 + +Stack = 1000 (bytes) + +Data = 0690 (bytes) + +Heap = 0800 (bytes) + +Data Segment = 1E90 (bytes) + +Initialized data = 03C0 (bytes) + +Code checksum = 33DF + +Data checksum = 3033 + +Code Version = 100F + +Priority = 0080 + +Header size = OOFO (bytes) + +Add 1 offset,len = 0040 (bytes), 0074 (bytes) +Add 2 offset,len = 00C0O (bytes), 0000 (bytes) +Add 3 offset,len = 00C0O (bytes), O02E (bytes) +Dyl count = 0000 + +Dyl table offset = 00000000 + +Image file size = 00002380 (bytes) + + +For the moment, the interesting data here is contained in the three lines of the form: + + +Add n offset,len + + +3-13 + + +GENERAL PROGRAMMING MANUAL + + +These give the offsets within the combined .app file to the embedded add-files. In this case, three of the +add-file slots are used; in general, any number from zero to four could be used. + + +For more discussion about various possible add-files, see the Series 3/3a Programming Guide. + + +A similar technique, using a DYL file list in a file with a .dfl extension, may be used to build any number +of dynamic library (DYL) files into an application. This topic is described in more detail in the Object +Oriented Programming Guide. + + +Changing the set of add-files in an image + + +The tool eremake.exe can be used to change the set of add-files built into an image file, without needing to +run the TopSpeed project system again, and without needing to have any files to hand apart from the +original image file. That is, image files can be remade with new add-file contents, without the earlier .exe, +.obj, or .c files being present. + + +One common use of eremake is to convert eg an English language version of an application into a +specified alternative language version. See the chapter Resource Files in the Additional System +Information manual for a general discussion of applications that can run in more than one language. + + +For example, suppose that an application Query has all its language text isolated in a resource file +query.rzc, which is one of the original add-files for the application. More precisely, suppose that the +original contents of guery.afl are + + +query.pic +query.rzc +query.shd + + +Suppose further that a French version of the resource file is produced: frquery.rzc, say. Then a new .afl +list should be created, frquery.afl say: + + +query.pic +frquery.rzc +query.shd + + +and eremake.exe should be invoked as follows: +eremake -afrquery -o..\french\query.app query.app + + +For a full list of possible parameters to eremake.exe, simply type eremake by itself. Note that eremake.exe +can be used to alter the priority, minimum heap, or version number of an image file. + + +In the above case, the "output" file ..\french\query.app is created by "remaking" query.app with add-files +listed in frquery.afl. + + +In this example, the files guery.pic and query.shd from the original version are also used for the French +version. Clearly, these could be changed too, if required. + + +Further uses of emake.exe + + +The actual conversion from .exe form into .img form is handled by the Psion-proprietary tool emake.exe, +according to the command + + +#run "emake —-b %af1l% -otname% -s -v%version% -p%priority% -hsheapsize% -%epoctype% +Sname%S.exe" + + +in the file tsprj.txt. +For a full list of possible parameters to emake.exe, just type emake by itself. + + +Note in particular that emake can produce other forms of final output, apart from .img files. This is +determined by the sepoctype variable in the above command, which by default takes the value t1. Other +possible values are t2 through +4: + + +tl makes an image file, with characteristic extension .img + +t2 makes a logical device driver, with characteristic extension .ldd +t3 makes a physical device driver, with characteristic extension .pdd +t4 makes a dynamic library, with characteristic extension .dyl. + + +Logical and physical device drivers are further discussed in the Writing Device Drivers chapter in the +Additional System Information manual. Dynamic libraries are discussed in the Object Oriented +Programming chapter of the PLIB Reference manual, and in the Object Oriented Programming Guide. + + +3-14 + + +CHAPTER 4 + + +NOTES ON CLIB + + +This chapter provides some additional information about the implementation of CLIB, the version of the +TopSpeed C library for the Epoc operating system. It need be read only by developers who wish to use +CLIB (for example, to port existing code from another program). Developers who stick to PLIB can skip + + +this chapter entirely. + + +The difference between PLIB and CLIB is explained in the previous chapter. + + +Functions missing from the MS-DOS Jpi C library + + +The following functions are not included in the EPOC version of CLIB because they rely on the IBM PC +hardware, far or huge pointers, or direct MS-DOS functions calls. For many of the missing function calls +there is an equivalent function or set of functions which may be called from either PLIB or WLIB. + + +absread + +_arc + +bdos + +biosdisk +biosmemory +_bios_disk +_bios_memsize +_bios_timeofday +_clearscreen +ctrlbrk + +delay +_dosbeginthread +_dosfreestack +dos creat +_dos_findnext +_dos_getdiskfree +_dos_getftime +_dos_keep +_dos_setblock +_dos_setfileattr +dos. setvect +_expand + +execve +farcoreleft +farrealloc +_ffree +_fheapwalk +_fmsize +_frealloc +_getbkcolor +getcurdir +getdta +_getfillmask +_getlogcoord +getpsp + + +abswrite + +at + +bdosptr +biosequip +biosprint +_bios_equiplist +_bios_printer +Jochain intr +convertcoords +_cube +_directwrite +_dosendthread +_dos_allocmem +_dos_creatnew +_dos_freemem +_dos_getdrive +_dos_gettime +_dos_open +dos_setdate +_dos_setftime +_dos_write +execle +execvpe +farfree +fcalloc +_fheapchk +_floodfill +_FP_OFF +freemem +getcbrk +_getcurrentposition +getfat +_getimage +_getphyscoord + + +gettime + + +allocmem +Awaited +bioscom +bioskey +biostime +_bios_keybrd +_bios_serialcom +change + +country + +Delay +_displaycursor +dosexterr +ados_close +_dos_findfirst +_dos_getdate +_dos_getfileattr +_dos_getvect +dos read +_dos_setdrive +_dos_settime +_ellipse +execlpe +farcalloc +farmalloc +_fexpand +_fheapset +_fmalloc +_FP_SEG +geninterrupt +_getcolor +getdfree +getfatd +_getlinestyle +_getpixel +gettext + + +4-1 + + +GENERAL PROGRAMMING MANUAL + + +_gettextcolor gettextinfo _gettextposition +getvect getverify _getvideoconfig +halloc _harderr _hardresume +_hardretn hfree hide + +highvideo hmemccpy hmemchr + +hmemcmp hmemcpy hmemicmp +hmemset hrealloc info + +Init intdos intdosx + +ioctl keep _lineto + +Lock locking lowvideo + +mktemp MK_FP movedata +movetext _moveto ncalloc_ + + +_ms_cursor +_ms_getpage +_ms_getsensitivity +_ms_reset +_ms_setdouble +_ms_setmickeys + + +_ms_setrange + + +_ms_driversize +_ms_getpress +_ms_getstatus +_ms_restoredriver +_ms_setgraphcursor +_ms_setpage + + +_ms_setsensitivity + + +_ms_getmotion +_ms_getrelease +_ms_lightpen +_ms_savedriver +_ms_setinterrupt +_ms_setposition + + +_ms_settextcursor + + +_ms_swapinterrupt _ms_updatescreen normvideo +nosound Notify obsucredat +_outtext palettecolor palettecolorused +paletteopen parsfnm peek + +peekb _pie poke + +pokeb _polygon putbeneath +_putimage putontop puttext +randbrd randbwr readbufferln +_rectangle _remapallpallete _remappallete +_selectpalette SEND _setactivepage +_stbkcolor setblock setcbrk +_setcliprgn _setcolor setdta +setftime _setfillmask setframe +_setlinestyle setlogorg setpalette +setpalettecolor _setpixel _settextcolor +_settextposition _settextwindow settitle +setvect setverify _setvideomode +_setviewport _setvsualpage snapshot + +sound spawnle spawnlpe +spawnve spawnvpe StartProcess +StartScheduler StopProcess StopScheduler +tempnam textattr textbackground +textcolor textmode tmpnam + +top Unlock use + +used WAIT window +windowclose windowopen _wrapon +_wrbufferlin + +int86x + + +int 86x is implemented by exactly the same code as int 86, ie the values in the segment registers struct are +ignored. This is because in the pure small model ps=zs=ss and hence there is never any need to change +the values in the segment registers. + + +intr +As for int86x above, the values in the segment registers are ignored. +File handle conversion routine + + +void *getRealHandle(int handle); + + +Returns a PLIB file handle, given a CLIB file handle. Returns nut if the handle is not currently +allocated. + + +4-2 + + +4 NOTES ON CLIB + + +The console channel + + +Programs built with the CLIB start-up module automatically open a console channel. The channel is also +automatically assigned to stdin, stdout and stderr, unless they have been redirected. + + +It may prove useful to get the actual PLIB handle for the console channel. This can be achieved by either +calling getRealHandle(fileno(stderr)) or by referencing the global _winHandle as follows: + + +extern void *winHandle; + + +You can prevent the automatic opening of a console channel by defining the function p_xwind in your +code, as in the following example: + + +extern void *winHandle; + + +void p_xwind (void) +{ +winHandle=(void *)1; + + +} + + +int main (void) + + +{ + + +return (0); + + +} + + +You should ignore the warning, given during the linking of your program, that the symbol _p_xwind is +duplicated. + + +If you use this technique your program should not, of course, make any reference to stdin, stdout or +stderr, unless you have redirected them. Setting winHandle to | (an illegal value for a handle) will +guarantee that any such reference will fail with a panic. + + +MS-DOS file names + + +Applications written for the Epoc O/S should in general avoid making any assumptions about file names +(see the Files chapter in the Plib Reference manual) and should use p_fparse and p_chdir to manipulate +file names and navigate directory paths. However the Loc: : file system on all SIBO machines is totally +MS-DOS compatible. Thus CLIB supports the TopSpeed STD C library functions findfirst, findnext, +getcwd, etc which rely on MS-DOS naming conventions. However if an attempt is made to use these +functions on other filing systems, such as rem: :, the routines will return an error. + + +Floating point emulator + + +As the SIBO architecture does not allow for an 8087 maths coprocessor, all floating point is performed by +software emulation of the 8087. + + +Normally the emulator code would be linked in with your program for MS-DOS exe's, but under Epoc O/S +the emulator is provided by an LDD called SYS$8087.LDD in \sibosdk\lib\. Any programs requiring the +emulator will automatically load the LDD and free it again when it is no longer required. This has the +advantage of saving about 8K of code from your program and allows the LDD to be shared by multiple +processes. + + +The C startup module (see r_emul.a) will look for the LDD in the directory in which your program was +executed. If it is not found the it will use the environment variable ems (remember to use capitals for the +name as environment variables in Epoc O/S are case sensitive). + + +Panic 80 + + +An application which terminates with a "panic 80" before it even starts has almost certainly failed to +locate SYS$8087.LDD. There are three steps that can be taken to avoid the panic: + + +move a copy of the LDD into the directory where the program will execute from +set the environment variable ems appropriately (eg using a short program) +rewrite the program so that it does not require the use of the LDD. + + +See the Floating Point chapter of the Plib Reference manual for some more details. + + +GENERAL PROGRAMMING MANUAL + + +Note that floating point instructions can easily be generated unexpectedly (eg to push or pop floating point +registers) if the recommended build configuration pragmas are "improved" in any way - resulting in panic +80s "out of the blue". If in doubt, inspect the object code using the SIBO Debugger (or use the TopSpeed +disassembler, tsda). + + +Building the CLIB library and header objects + + +To build the CLIB library you must have purchased the Professional variant of the SIBO SDK. This +version includes the C Library Source Kit and the corresponding EPOC CLIB Library Source. Since some +of the EPOC CLIB source modules are written in C++, you will also need to have separately purchased +TopSpeed C++. + + +Simply startup TS in the SRC directory of SIBOSDK. Select CLIB as the project file and then MAKE the +project. The libraries and objects will be generated in the SRC directory and need to be copied into the LIB +directory. There is a batch file IVST.BAT which will do this for you. + + +Note that, in addition to the CLIB library, there is also an RLIB component. This contains elements that +are common between CLIB and PLIB. + + +The source code modules for PLIB and WLIB are currently in Turbo Assembler format and are not +buildable using the TopSpeed assembler. They have not been included in this release of the SDK. The vast +majority in any case are simple shells which just juggle registers. + + +Cautionary note + + +It is advisable to tread cautiously when changing the library, and under no circumstances should the +pragmas be changed in either TSPRJ.TXT or STDEPOC.H. + + +CHAPTER 5 + + +FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +Introduction + + +In some ways, this chapter may be viewed as being among the most important in the whole of the SDK. +Follow the Guide-lines here and your programs have a good chance of possessing the following qualities: + + +user responsiveness users will not be kept waiting impatiently if they want to interact +with an application whilst it is busy - eg to cancel some operation +part-way completed + + +error robustness data will not suddenly be lost when run-time errors occur such as +shortage of system memory (bear in mind that such errors are +almost inevitable on a multi-tasking computer, when the system +memory can become unexpectedly used up by other applications) + + +architectural robustness changes in user requirements or in implementation tactics should +not lead to the whole code becoming unmaintainable. + + +Of course, practice of standard general programming principles - such as modular programming, data +hiding, egoless programming, designing prior to coding (not to mention adequate requirements +specification prior to design), and a structured approach to validation and testing - all have important +roles to play in the production of quality SIBO applications. But there are additional programming +principles that have particular importance within the SIBO environment, and it is these that this chapter +addresses. These principles should complement the ones good programmers from other backgrounds +already practice. + + +Incidentally, just as the merits of the above-mentioned "standard" programming principles are not always +immediately obvious (data hiding is a good example), but rather have to be learned, so it is with some of +the principles outlined in this chapter. Their importance has become clear to the programming team at +Psion only gradually, over several years’ experience. It is understandable that experienced programmers +from other backgrounds may wish to rush over this chapter, believing its contents to be inapplicable to +them, but that would almost certainly be a mistake. + + +Again, there is of course no substitute for a wide-ranging knowledge of which library functions are +available. Developers wishing to produce quality applications will naturally have to spend some +considerable time familiarising themselves with the contents of the reference manuals within the SDK, so +as to be able to spot the right function to use in any particular coding situation. This knowledge cannot be +acquired simply by assenting to the set of programming principles covered in this chapter. But conversely, +wide knowledge of the set of available function calls is insufficient, by itself, to produce programs with the +traits listed at the start of this chapter. + + +Other related documentation + + +Applications which are multi-lingual (eg which present English language messages on an English +language computer, French language messages on a French language computer, and so on) pose their own +set of programming problems. These are discussed in the course of the Resource Files chapter of the +Additional System Information manual. (Resource files are a tool of particular importance for multi- +lingual applications.) Note that these problems are shared between applications which are actually multi- +lingual and those that are potentially multi-lingual: it is better to design support for multi-linguality in +from the start, than trying to add it on afterwards. + + +GENERAL PROGRAMMING MANUAL + + +Graphics programming has its own particular set of do's and dont's, in order that (for example) flicker- +free redrawing and automated screen update take place. These are discussed at various places in the SDK, +for example, in the Window Server Reference manual, and also in the Programming in HWIF manual. + + +Avoidance of excessive RAM usage, and also of "stack windup", are also of considerable importance +within the SIBO architecture. Specific advice on these regards are scattered throughout the SDK; the +present brief note simply has the purpose of drawing attention to the topic. + + +Finally, the task of designing the user interface (menus, dialogs, and so on) is another that poses its own +special problems - programmers who labour under the misapprehension that user interfaces are "easy" to +design almost invariably produce poor user interfaces. Guide-lines on these matters may be found within +the object oriented documentation parts of the SDK. + + +The source code for the examples + + +The bulk of this chapter consists of a lengthy analysis of a suite of example programs. These build in four +stages - Events, Events2, Events3, and Events4 - to a program that can simultaneously process: + + +e keyboard input +e the expiry of a timer +e reports of the completion of a sub-process +e data received from a serial port +whilst all the time carrying on some compute-bound activity "in background" + + +At any given moment, the program cannot predict which of its five possible "event sources" will be the +next to require CPU. As such, the program amply demonstrates the three vital themes of multi- +threadedness, asynchronous i/o, and yielding CPU: + + +e = multi-threadedness means that more than one set of activity takes place simultaneously within +the program, with each different flow of activity being handled by its own "thread" of code + + +e¢ — asynchronous i/o means that the queuing of a read request (or write request) on an i/o channel is +separated in code from the completion of that request + + +e yielding CPU means that lengthy calculations are broken down into subcomponents that are +executed separately, with gaps in between so that some more urgent event source can be attended +to, if necessary. + + +Although the program itself has limited practical use, it demonstrates the basic architectural principles +that all sophisticated Epoc programs are bound to have to consider. + + +The source code for these four stages of Events can be installed from disc (SIBOSDK\DEMO), together +with that of an associated "sub-process" application, Subproc. Readers are urged to take the time to build +these applications and to experiment with them, in particular trying out some of the suggestions made in +this chapter for how these programs could be modified. + + +User interface + + +The user interface of these example programs has deliberately been kept spartan. All screen drawing is to +a "console terminal" that is 25 characters wide and 9 characters deep. + + +These decisions have the advantage that: + + +e the program works equally well on all different SIBO computers (even on the HC, where the +screen is smallest) + + +¢ considerations about interfacing with the Window Server - necessary in order to achieve more +graphically appealing displays - can be postponed while focusing instead on multi-threadedness, +asynchronous i/o, and yielding CPU. + + +Various examples of Window Server programs demonstrating multi-threadedness (et al) can be found +within the SDK. For example, the Writing Software for the HC chapter of the HC Programming Guide +discusses an application called Gauge, that will in fact run happily (with only minor adjustments) on a +Series 3. Again, the Programming in HWIF manual contains a large set of example programs, all of +which interface with the Window Server. + + +5-2 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +A first look at multiple event sources + + +The main routine in Events is as follows (the individual calls made, including the Plib calls, are discussed +below): + + +GLDEF_C VOID main(VOID) +{ +OpenConsole(); +DrawBorder() ; +OpenTimer () ; +timint=10; +QueueTimer (); +QueueKey () ; +FOREVER +{ +p_iowait (); +if (keystat!=E_FILE_PENDING) +{ +if (key. keycode==W_KEY_ESCAPE) +p_exit (0); +if (key.keycode>='1' && key.keycode<='9') +SetTimInt (2* (key. keycode-'0')); +QueueKey () ; +} +else if (timstat!=E_FILE_PENDING) +{ +if (counter++==MAX_COUNT) +counter=1; +DisplayCount (); +QueueTimer (); + + +} + + +} +Schematically, the code is as follows: + + +GLDEF_C VOID main(VOID) +{ +INITIALISE (); +QueueTimer () ; +QueueKey () ; +FOREVER + + +{ +p_iowait (); +if (keystat!=E_FILE_PENDING) +{ +PROCESS_KEY () ; +QueueKey () ; +} +else if (timstat!=E_FILE_PENDING) + + +{ +PROCESS_TIMER() ; +QueueTimer(); + + +} +} +in which it is clear that the program has two event sources - keypresses and the expiry of a timer. + + +What the program actually does is to update a numeric count (displayed on the screen) regularly, on a +timer. The rate at which the timer fires is determined by which keys the user presses: + + +e it starts off firing once every second + + +e if the user presses the 2 key, the timer changes to firing once every 2/5 of a second (so that the +numbers tick over more rapidly) + + +e if the user presses the 9 key, the timer changes to firing once every 9/5 of a second (so that the +numbers tick over more slowly) + + +GENERAL PROGRAMMING MANUAL + + +and so on. Further, every time a numeric key is pressed, the existing timer request is cancelled, and the +timer reset - so that pressing repeatedly on keys such as 8 and 9 can have the effect of "stalling" the +counter altogether. + + +The program exits in response to the ESC key being pressed. All other keys are ignored. + + +Remarks on timers + + +One simple approach to programming with delays is to call a function such as p_sleep, which effectively +suspends the application for a specified amount of time. + + +This approach could be adopted in Events, were it not for the fact that, when the application is suspended, +it cannot respond to a keypress. The keypress will only be received when the application "wakens up" +again. + + +Now this might not be too much of a loss for very small time delays, but it is of course unacceptable for +longer delays. For example, a program might wish to perform some housekeeping or maintenance once +every twenty four hours - or simply update the display in a dialog once every two seconds, whilst allowing +the user to cancel out of the dialog at any time. That is, whilst routines such as p_sleep certainly have a +role to play, they cannot handle all timer requirements in programs. + + +A next possible approach would be to design a routine which, when called, suspended the application until +the specified time elapsed or a keypress is received - whichever happens first. Indeed, there is a call with +just this specification in the Opl programming language (pause when used with a negative time delay). + + +Actually, this routine would satisfy the requirements of Events perfectly. However, it has the severe +drawback of lack of architectural openness. That is, suppose the application has to be modified at a later +date, to be able to respond to another sort of event source - eg the arrival of data at a serial port, or an +interprocess message from another application. Alternatively, the application may need to carry on some +continuous activity, whilst waiting for the timer to expire. In either case, a more general approach is +required. + + +This more general approach is the mechanism by which the queuing of a timer is separated, in code, from +the completion of the timer. In the above code, the timer is queued by the call queueTimer, whereas the +completion of the timer occurs within the p_iowait call. (See later for the details.) + + +This kind of code separation between the queuing of a request and the completion of the request is known +as asynchronous - because there is no automatic synchronisation of the two phases (as occurs, for +example, in a call such as p_sleep). + + +Remarks on keypresses + + +A routine such as p_getch is to keypresses what p_sleep is to timers - in both cases, the program is +effectively suspended until the request is completely satisfied. + + +Just as there is a place for p_sleep in programming, so also there is a place for p_getch. However, each is +generally inappropriate when there is more than one event source current - as here. + + +So the call p_getch is split into two parts: the request for a keypress to be delivered, inside the call +Queuekey, and the delivery of the keypress - inside p_iowait. + + +More on p_iowait + + +The call p_iowait is where the application gets suspended, while it waits for the completion of some or +other event. But whilst p_sleep only returns when the associated timer expires, and p_getch only returns +when a keypress is delivered, p_iowait returns when any known event has completed. + + +Of course, sometimes the application won't get suspended at all when it calls p_iowait - on account of a +queued request already having completed. For example, during the time Events is inside the code +PROCESS_TIMER, the user may have pressed a key, in which case the subsequent call to p_iowait will +return immediately (not that the application needs to worry about this, however). + + +The way p_iowait works is by consulting the value of the i/o semaphore for the process. Each process has +an i/o semaphore assigned to it. These semaphores are maintained in the private data space of the +operating system. + + +An i/o semaphore commonly has its value changed in either of two ways: +e it is decremented whenever a call to p_iowait is made + + +e it is incremented whenever some piece of software "signals" the application. + + +5-4 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +For example, whenever a timer expires, the operating system timer device signals the application which +owns the timer. Again, whenever the Window Server delivers a keypress to an application, it signals that +application. In general, the completion of any i/o request always involves the application being signalled. + + +The i/o semaphore of an application initially has the value zero. A call to p_iowait only returns when the +i/o semaphore is non-negative. Given that the call to p_iowait starts by decrementing the semaphore, the +call will return only when "something has happened". + + +For more details about p_iowait and i/o semaphores in general, see the Plib Reference manual. + + +Note that the SIBO Debugger has a menu command (Process Status) which displays the value of the i/o +semaphore of a process (amongst other information). The Spy application discussed in the Series 3 +Programming Guide has a similar feature, which allows the i/o semaphores of all different running +processes to be viewed simultaneously. + + +Status words: the other side of p_iowait + + +When a program returns from a call to p_sleep, it knows that it is a timer that has expired. Likewise, +when a program returns from a call to p_getch, it knows that a keypress has been delivered. However, +when a call to p_iowait returns, no such information is immediately available. All the application knows +at this point is that some event has completed - not which event. + + +In general, the task of determining which events are indeed ready to be processed involves two factors: +¢ knowing which event sources are active - having had requests made on them +e knowing which of this subset have completed their requests. + + +For the moment, the first of these points can be ignored (but see later), with attention given to the notion +of the status word of an asynchronous request: + + +e when the request is made, an address of a status word is specified (recall that a "word" is two +adjacent bytes) + + +e when the request is made, the value E_rFILE_PENDING gets written to this word + + +e when the request completes, a value other than &_FILE_PENDING is written to this word (the +actual value varying depending on the type of asynchronous request) + + +Writing to the status word takes place just before the i/o semaphore for the application is signalled. Both +these steps are integral to the SIBO mechanism of p_iowait. + + +All this explains the code in Events immediately after the call to p_iowait: the different status words are +polled in turn, in order to find one whose value is no longer E_FILE_PENDING. + + +Prioritisation of event sources + + +Note that the order in which the status words are polled implicitly prioritises the different event sources. +For it is possible for more than one asynchronous event to have completed; in this case, the first one of the +two polled will be the one which gets the first response. + + +Note in particular that the order in which events are processed need bear no direct relation to the order in +which the events actually completed. An event source lower down the priority listing can be "locked out" +by rapidly firing event sources higher in the listing. In fact, code can often be written which depends on +this prioritisation - so that a lower priority event source is only serviced when all higher priority event +sources have quietened down. + + +I/O devices in general + + +In this example, keypresses are delivered by the console device. Likewise, timer expiry is handled by the +timer device. The console device and the timer device are both instances of general so-called i/o devices, +all of which possess a common interface: + + +e before using an i/o device, an application has to open a channel to it +© once opened, various services can be requested via the channel +e these services can all in principle be requested either synchronously or asynchronously + + +e if an i/o device channel is no longer needed, the resources it consumes (eg memory) can be +released by closing the channel. + + +GENERAL PROGRAMMING MANUAL + + +Channels to i/o devices are opened by means of the p_open call, in which the 1/o device has to be specified +by name. Another parameter to the p_open call also defines where the handle of the channel will be +written. + + +The handle returned by p_open can then be used to request other services from the i/o device. It can also +be passed as a parameter to p_close, to close the channel down again. + + +The way synchronous requests are made, via an i/o channel, is to use a p_iow call (or a convenience +routine that layers over this). Asynchronous requests are made using a p_ioa (or p_ioc) call. + + +For example, the call to position the console cursor, inside the routine write in events.c, is as follows: + + +P_POINT pos; +WORD func; + + +pOS.xX=X; +Pos.y=y; + +func=P_SCR_POSA; + +p_iow4 (conH, P_FSET, &func, &pos) ; + + +This is a synchronous call because there is no point in calling it asynchronously: the effect of this call +(setting the cursor position) is always (virtually) immediate: there is no scope for any extended delay as it +is carried out. + + +On the other hand, the code for queuekKey is + + +LOCAL_C VOID QueueKey (VOID) +{ +p_ioa4 (conH, P_FREAD, &keystat, &key) ; +} + + +which is clearly asynchronous. (The 'a' in "p_ioa" stands for asynchronous.) + + +By chance, it turns out that these two calls to p_ioa and p_iow have the same number of parameters. This, +however, is only the case because the P_FREAD request requires one less parameter than the P_FSET +request. In general, an asynchronous request always has one more parameter than the corresponding +synchronous request - namely the status word, whose address has to be passed in the asynchronous case. + + +For more on the p_io? functions (including the significance of the numeric suffices to the function +names), see the Plib Reference manual. + + +The console device + + +The Events application uses the console device - as opposed to just making calls like p_printf - for two +reasons: + + +e as discussed already, the console device supports an asynchronous version of p_getch + + +e the console device supports repositioning of the cursor position - which fact is relied upon heavily +in the application. + + +For a full specification of the console device, see the corresponding chapter in the //O Devices Reference +manual. + + +How to cancel a timer + + +The code inside cancelTimer merits some attention: + + +LOCAL_C VOID CancelTimer (VOID) +{ +p_iow2 (timH, P_FCANCEL) ; +p_waitstat (&timstat) ; +} + + +First, the P_FCANCEL service is requested. This is itself a synchronous request, completing at once. + + +However, the way the generic service P_FCANCEL works in device drivers is never to retract the earlier +request, but rather to precipitate its completion. It cannot retract it in general because it may already have +completed by the time the p_FcANCEL request is made: + + +e if the request has already completed, the p_rcaNncEL does precisely nothing + + +e if the request is still outstanding, it is completed forthwith, with the value E_FILE_caANcEL being +written to the status word, and with the application being signalled (on account of the fact that +the earlier request has now completed, albeit precipitously). + + +5-6 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +In either case, the application will be signalled - either before the p_rcanczg , or after it. Accordingly, this +signal has to be "processed" (or "used up"). This is the purpose of the subsequent call to p_waitstat. For +more details about p_waitstat, see the Plib Reference manual. + + +Omitting to call p_waitstat after making a p_FCANCEL request is a common error. The result of this error +is that the next call to p_iowait will return at once, even though none of the remaining active event +sources is ready to deliver an event. + + +For more details about the timer device in general, see the chapter Time, Timers and Dates in the Plib +Reference manual. + + +Where to declare status words + + +On the subject of common programming errors in conjunction with asynchronous i/o, perhaps the most +common one has yet to be mentioned. This is the mistake of declaring status words on the stack of some +routine which will have returned long before the asynchronous request completes. The status word will +now be a piece of random data - perhaps on the stack of another routine - and random damage can ensue +when it is in due course written to. + + +Status words should always be declared either in static data (as in Events), or in a control block allocated +from the heap. + + +A first look at error handling + + +Every time a function call is written into a SIBO program, the programmer should consider the question: +could a run-time error occur in the middle of this function? And if so, what would happen? + + +Chief amongst these possible errors is lack of memory. This can occur in three different ways: +e the application has reached the limit of its 64k data segment + + +e the application is using less than 64k itself, but there is no system memory available for it to be +given more heap space + + +e another program with which the application is cooperating runs out of memory. +Other errors that need to be considered include: + + +e resources not being available because another application is already using them (eg serial port or +sound device driver, or even a file that is currently open by another application) + + +e disk-based errors such as disk full, disk corrupt, or disk removed +e the unexpected disappearance of the remote filing system (rem: :) +e comms failures such as serial overrun, parity error, or line failure. + + +These errors cannot be dismissed with the philosophy that, in an ideal world, they will not happen. +Instead, they can and will happen, despite the best endeavours of the programmer. SSDs becoming full up, +comms cables being removed, or a file already being open by another program, are all problems that arise +naturally in the operation of a SIBO computer. + + +Whatever the cause of a run-time error, applications should take every care that no data entered by the +user is lost. Another requirement - to avoid parts of memory being permanently tied up for no purpose - is +that partly assembled data constructs which cannot be completely assembled, owing to a run-time error at +a later stage, should be carefully disassembled again. + + +Error handling in Events + + +Looking at the source code in events.c, it is clear that three different types of error are considered: +e failure to open the timer device +e failure to open the console device + + +e failure to set the size of the console screen. + + +GENERAL PROGRAMMING MANUAL + + +None of the other function calls have any possibility of run-time error, as can be verified by considering +them all individually. (In fact, considering every call individually for possibilities of run-time error has to +be the norm when developing applications.) + + +It is worth considering the above three possible errors in a little more detail. For example, opening a timer +can fail for two reasons: + + +e lack of memory for the timer control block in the application data space +e lack of memory in the operating system dataspace for the real timer entry. + + +Now whilst an application may be able to ensure that the first possibility never arises - by means of setting +its minimum heap appropriately - it can never be sure of preventing the second case. The number of +timers allocated in operating system dataspace depends not on circumstances within the original +application, but rather on what other applications have done. If other applications running simultaneously +happen to make heavy use of timer resources, the operating system may not be able to set aside the one +timer channel requested by Events. + + +Should this occur, the code in openTimer and Check ensure that a suitable error message is passed back to +the user. The user can then take action to shut down some of the other applications running +simultaneously on the computer, before trying to start Events again. + + +The case of the channel to the console device is similar. This time, it is resources of (for example) the +Window Server which may be unable to meet the request made. Likewise when the console window is +sized (at which time various arrays or back-up bitmaps need to be allocated). + + +Fatal errors and non-fatal errors + + +The three possible errors in Events are all treated as being fatal: the application initialisation fails, so the +application terminates. + + +This kind of action makes good sense for errors during the initialisation of an application, but cannot on +the whole be tolerated for errors during the main phase of an application (ie after the initialisation is +complete). By this time, the user may well have committed some data into the application, which would be +lost if the application suddenly terminated. + + +In these cases, a retry philosophy is much more appropriate: the application cleans up any interim semi- +allocated resources, "rolls back" to its previous good state, and presents an error message informing the + +user what has happened. It is up to the user to try to correct the error condition, and then re-initiate the + +previous action. + + +When resources need to be tidied explicitly + + +It may be noted that there are no calls to p_close in events.c. These calls are unnecessary in this program, +because the channels are automatically closed, by the operating system, when the application exits. + + +This situation must be contrasted carefully with that when a resource (such as a channel to an i/o device) +is used transiently by an application. In this case, it must be freed as soon as it is no longer needed. + + +Inter-Process Communication Events2 and Subproc + + +Events2 extends the functionality of Events by supporting the facility to launch a sub-process. A sub- +process is automatically started during program initialisation, and once it has terminated, the user can +press ENTER to re-launch it again. + + +The sub-process mimics the carrying out of some extended activity. When it finishes, it signals the fact of +its completion to Events2, together with an "answer", which Events2 displays on the screen. This answer +has in fact been calculated from a parameter passed by Events2 to Subproc on the command line. + + +Subproc and Events2 therefore carry out a restricted form of inter-process communication, and thereby +illustrate some of the multi-tasking possibilities in writing software for SIBO computers. + + +A third event source + + +Events2 remains alert to the possibility of a signal from Subproc, even though it is busy responding to +timer events and keyboard events. Events2 manages this via a straightforward extension of the +architecture in Events: one more "event source" is added into the picture. + + +5-8 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +Thus there is one more status word - substat - and one more test in the main loop in main: + + +else if (substat!=E_FILE_PENDING) +Report Sub () ; + + +That is, whereas main used to poll up to two status words, on returning from a call to p_iowait, it now +polls up to three status words: subst at in addition to keystat and timstat. + + +However, this new event source differs from the previous two in that it is not an i/o device. There is no +p_ioa call to request notification from Subproc; rather, the corresponding "queue" call is p_1ogona. + + +In the line of code + + +p_logona (pid, &ésubstat) ; + + +the calling application (Events2) is requesting asynchronous notification of the eventual termination of the +process identified by pia. This notification consists of two parts (now familiar): + + +e avalue other than &_FILE_PENDING is written into substat +e the application is signalled (so that its i/o semaphore increments). + + +How Events2 passes data to Subproc + + +Events2 passes its original data to Subproc via the command line. + + +In any case like this, there has to be an agreement between the two processes as to the format of the +command line. Here, the protocol is established in the shared header file subproc.h, which defines the +following struct: + + +typedef struct +{ +HANDLE pid; +VOID *poff; +ULONG data; +} SUBPROC_CL; + + +The members of this struct serve the following purposes: +pid identifies the process which launched Subproc (ie Events2) + + +poff an address within the dataspace of Events2 where Subproc should in due course write back +the "answer" it discovers + + +data _ the original seed data for Subproc to operate with. +The following code sets up this struct and creates and runs Subproc: + + +LOCAL_C VOID LaunchSub (VOID) + + +{ + +HANDLE pid; + +SUBPROC_CL cl; + +TEXT subname [P_FNAMESIZE]; + + +p_fparse ("subproc.img",DatCommandPtr, &ésubname[0],0); +cl.pid=p_getpid(); +cl.poff=(&answer) ; +cl.data=p_date(); +if ((pid=p_execc (&subname[0],&cl,sizeof (cl) )) <0) +{ +p_notifyerr(pid,"Failed to launch subprocess",0,0,0); +return; +} +p_logona (pid, &substat) ; +p_presume (pid) ; + + +} + + +The variable answer is a static. Clearly, it would be a significant error to include it on the stack of +LaunchSub, since this stack will have unwound before answer gets written to (by Subproc). + + +As can be seen, in this example, the data value passed to Subproc is just the current time/date, as returned +by p_date. + + +GENERAL PROGRAMMING MANUAL + + +Note the call to p_fparse, which calculates the presumed full pathname of subproc.img, under the +assumption that this is in the same directory as events2.img. (The full path of events2.img is written to +DatCommandPtr by the operating system, when Events2 starts running.) + + +For more on the operation of p_logona, see the Plib Reference manual. + + +The code in Subproc + + +The code in subproc.c is very straightforward: + + +#include +#include +#include +#include +#include "subproc.h" + + +GLREF_C TEXT *DatCommandPtr; + + +GLDEF_C INT main(VOID) +{ +TEXT *pb; +SUBPROC_CL *pcl; +UWORD answer; +WORD logstat; + + +pb=DatCommandPtr+p_slen(DatCommandPtr) +1; + +if (*pb!=sizeof (SUBPROC_CL) ) +return (E_GEN_ARG) ; + +pcl=(SUBPROC_CL *) (pbt+1); + +if (!p_logona(pcl->pid, &logstat) ) +{ +answer=(UWORD) (p_randl (&pcl->data) % (2*60*32) ); +p_sleept (answer) ; +if (logstat<0) + +p_pcpyto (pcl->pid, pcl->poff, &answer, sizeof (UWORD) ) ; + +} + +return (0); + + +} + + +The way Subproc mimics performing a lengthy calculation is simply to call p_sleept, for some random +period up to two minutes in duration. + + +Note that Subproc exits at once if the command line passed to it is not of the expected type. On most SIBO +computers, the result of an application calling p_exit with a negative value is a Notifier reporting the +abnormal exit. + + +Note too that just as Events2 asynchronously logs onto Subproc, Subproc logs onto Events2. However, this +is for a different reason. Namely, Events2 might terminate in the meantime, while Subproc is busy +"calculating". In this case, a non-negative number will be written into logstat. If Subproc ignored this +fact and proceeded regardless to p_pcpyto data into the process currently having identifier pc1->pia, in +all probability the call would fail - process identifiers take a long time to get re-used, and the operating +system would ignore the p_pcpyto on account of a non-existent pid being specified. But there is always an +outside chance that the pia will indeed be re-used by the time Subproc has completed - in which case the +p_pepyto could cause random damage to a blameless application. + + +The reason there is a test on the result of the p_logona call in Subproc is to guard against the rare case of +Events2 exiting even before Subproc reaches the p_logona call. + + +Mechanisms for inter-process communication + + +The above mechanism is a very simple illustration of a form of IPC (inter-process communication). Epoc +supports a considerable range of IPC services, chief amongst them being IPC messaging. + + +Messaging also involves the same principles of status words, synchronous or asynchronous requests, and +signalling an application. In some cases, one process will signal another one explicitly, using the function +p_iosignalbypid; in other cases, the signalling is performed by the operating system, say in response to a +p_mfree call in an application (indicating that the message sent has been processed). + + +See the Plib Reference manual for more details of these different forms of IPC. + + +5-10 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +Debugging cooperating applications +One method of debugging the interaction between Events2 and Subproc is as follows: +e leave both image files in the same directory on the PC +e in that directory, type sdbg events2 to start debugging Events2 +e place a breakpoint on the p_logona call in events2.c +e run Events2 until it reaches this breakpoint + + +e note incidentally that the p_fparse call in Launchsub automatically deduces that since Events2 +has been launched from a remote directory (ie on the PC), Subproc should also be launched (if +possible) from this same remote directory + + +e when the Debugger breaks at the p_logona call, the code and data segments for Subproc will +already be created (by virtue of the prior p_execc call) + + +e refresh the main list of remote processes; select Subproc and break into it (use the Break Into +menu command) + + +e scan to the beginning of main in subproc.c and set a breakpoint there +e issue the Apply Breakpoints menu command (whence the windows will go blank) +e switch back to the window debugging Events2 and step over the p_presume call + + +e this will have the effect of starting the execution in Subproc - in which case the breakpoint in +main will be reached. + + +Debugging now continues, with two different debugging windows - one for Events2, and one for Subproc. + + +Error handling in Events2 + + +The call to p_execc in Events2 can fail for a variety of reasons - chief amongst them lack of system +memory. Note that Events2 does not treat this as a fatal error; rather, the error is reported to the user, and +the program carries on (taking care to leave the internal variable subexist set correctly). + + +The user has the opportunity to respond to the message by freeing up some system memory, and then +pressing ENTER to make another attempt to launch Subproc. + + +Socially responsible programming in Events2 + + +There is one more change between events.c and events2.c, which actually corrects a bug deliberately left +in Events. This change is the addition of a call to p_unmarka at the start of main. + + +If a SIBO computer is left switched on while Events is running, it will fail to auto-switch-off subsequently. +This is because of the regular timer activity in the program, which keeps resetting the inactivity counter of +the computer. + + +Suppose that the user turns the computer off explicitly. However, if an alarm rings at some stage, Events +will start running again, and if the user is not at hand to notice the alarm, the result will soon be flattened +batteries - regardless of the auto-switch-off setting. (Try it and see.) + + +However, the addition of the call to p_unmarka prevents any activity within Events2 from resetting the +inactivity counter. As a result, Events2 is much more socially responsible than its precursor. + + +See the Plib Reference manual for more details on p_unmarka. + + +Data received from a serial port + + +Events3 extends the functionality of Events2 by including yet another event source: data received from a +serial port. Characters are read one at a time from the serial port and, if they are printable, they are echoed +onto the screen. + + +For background information on the serial port, see the Serial Port chapter of the I/O Devices Reference +manual. + + +5-11 + + +GENERAL PROGRAMMING MANUAL + + +Opening the serial port + + +The serial port is an i/o device: before services such as P_FREAD can be requested from it, a suitable +channel has to be opened. + + +The contents of the openSer routine in events3.c are as follows: + + +LOCAL_C VOID OpenSer () + + +{ +INT ret; + + +ret=p_open(&serH, "TTY:B",-1); +if (ret<0) +ret=p_open(&serH, "TTY:A",-1); +if (ret<0) +{ +p_notifyerr(ret,"Opening serial port",0,0,0); +serH=0; +} +} + + +If the attempt to open "TTyv:8B" fails, an attempt is made to open "TTy:A" instead; only if both attempts fail +is this fact reported to the user. + + +Typical reasons for it being impossible to open a serial port are that port already being in use (eg by Link +software) or the port not being physically present. + + +In contrast to the retry mechanism for launching Subproc which is built into Events3, there is no +corresponding retry mechanism for opening the serial port. A trivial amendment could be made to allow + + +this. + + +Active and inactive event sources + + +Events3 adds this fourth event source to the bottom of the prioritised list in main, which now has the +following schematic form: + + +GLDEF_C VOID main(VOID) +{ +INITIALISE(); +QueueTimer (); +QueueKey (); +LaunchSub () ; +QueueSer(); +FOREVER +{ +p_iowait (); +if (keystat!=E_FILE_PENDING) +{ +PROCESS_KEY (); +QueueKey (); +} +else if (timstat!=E_FILE_PENDING) +{ +PROCESS_TIMER() ; +QueueTimer (); +} +else if (subexist && substat!=E_FILE_PENDING) +Report Sub (); +else if (serH && serstat!=E_FILE_PENDING) +{ +p_tickle(); +DisplaySerChar (); +QueueSer (); + + +} + + +5-12 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +Note however that the test for whether to call Report sub has changed its form slightly. No longer is it +sufficient just to poll substat; it is also necessary to check on the current value of subexist: + + +e subexist is set to TRUE When Subproc is successfully launched +e¢ subexist 1s set back to FALSE whenever it is discovered that Subproc has completed +e thus the only time the value of substat should be polled is when subexist iS TRUE. + + +Without this double check, a variety of bugs can be demonstrated - all of which stem from serial port +events being misinterpreted as reports of Subevent completing. + + +Similarly, for the sake of correctness, the value of serx should be tested before going on to poll serstat: +serH is 0 if it has proved impossible to open a serial port. (Actually, no immediate harm will ensue if the +check on serH is omitted, given that this is the last of the event sources in the priority list.) + + +The reason no corresponding checks are required for the keyboard and timer event sources is that these +event sources are always active: + + +e the program terminates at once if it proves impossible to open a channel to these devices + + +e every time an event is delivered from these sources, another request (for yet another event) is +issued straightaway. + + +The variables serx and subexist in Events3 play the role of what are sometimes called active words for +their event sources - complementing the roles of their status words: + + +e active words have to be set and cleared by the application itself + + +e status words are written to by system software; generally, application software only reads the +values of status words + + +¢ active words are set when a request is made; status words are set when a request completes. + + +One other possible advantage in maintaining active words for event sources is to avoid making the +mistake of sending a Pp_FCANCEL request to an i/o channel which has not had a read request made on it. +Some i/o devices panic the application if this happens. + + +Debugging applications with serial comms +Programs involving serial comms are inevitably harder to debug than without serial comms. + + +This is because the Debugger itself uses up one serial port on the computer. In general, Events3 will be +unable to open any serial port currently being used by Link software (such as the SIBO Debugger). + + +One possibility, however, is to use say port a to debug the application, and send serial data to the +application via port B. + + +The role of p_tickle + + +Whenever serial port data is received by Events3, a call is made to p_tickle to reset the inactivity +counter. This prevents the computer from auto-switching off part way through processing an incoming +stream of serial data. + + +Note that there is no requirement to make a corresponding call whenever a keypress is received, since the +operating system does this automatically. + + +Finally, it would of course be an error to make this call whenever the timer expires - since this would keep +the computer permanently switched on. + + +Note that some early versions of the Epoc operating system may fail to support p_tickle (versions prior +to 2.11). + + +Yielding CPU in compute-intensive programs + + +Events4 adds in yet another type of event source - one that is subtly different from all the others so far +introduced. This is an event source which is always ready to run immediately. However, it is deliberately +located in a low position in the priority listing, to ensure that other event sources are processed +preferentially. + + +5-13 + + +GENERAL PROGRAMMING MANUAL + + +A real-life example of such an event source would be a recalculation computation in a spreadsheet, or a +reformatting calculation in a word processor. Again, a long file operation - such as building the index of a +DBF file - should also be broken up into chunks, so as to let the application to respond to other event +sources in the meantime. Finally, a game may think indefinitely until such time as it is told to stop. + + +In Events4, this continual "thinking" is simulated by continually adjusting the display of part of the +boundary of the console window. The constant visible change is meant to reflect constant internal activity. + + +Idle objects + + +Event sources such as just discussed are sometimes referred to as idle objects. The meaning of the name is +that they only get a chance to run when the application is otherwise idle. For example, if an application is +busy responding to keypresses, it is certainly not idle, and so any idle objects have no opportunity to run. + + +On the other hand, this name is of course potentially misleading, since the activity represented by the idle +object is anything but idle. + + +The meaning of calling p_iosignal + + +The contents of the "queue" routine for the idle object in Events4 is just the single line +p_iosignal(); + + +Since there is no genuine i/o connected with an idle object, there is no system software that automatically +signals the application when the i/o has completed. That is why the "queue" routine itself calls +p_iosignal. + + +At the same time, it might be thought that this routine should write to a status word. Actually, however, +there is no point in doing so: what matters is simply that the event source is active; in that case, it is +automatically ready to deliver an "event" (ie to take more CPU). + + +Just as some event sources have no need to maintain an active word (since they are always active), others +(ie idle objects) have no need to maintain a status word, since whenever they are active, they are ready to +deliver an event. + + +One drawback of continuous activity + + +Interestingly, Events4 has re-introduced the "stay awake" bug that Events2 managed to fix from Events. +This fact can easily be verified by user experimentation. + + +The call make to p_unmarka is now ineffective since, as is explained in the Plib Reference manual +(section on p_unmarka), it is the sys$null process which administers the auto-switch-off, yet it will have no +opportunity to run if any other applications are continually running. The point is that the priority of +sys$null is lower than that of any other process. + + +One possible solution here is to call, say, p_sleept (2) every so often, to try to allow sys$null to run. +However, this too will fail in the rare case when there are two similarly anti-social applications running +simultaneously on the SIBO computer. Even if they both call p_sleept periodically, there is little chance +of them both sleeping at the same time - which would be required in order for sys$null to run. + + +A better solution is to call p_allowoff from time to time. By doing so an application assumes +responsibility for performing the auto-switch-off that would otherwise be done by sys$null if it had an +opportunity to run. + + +Remarks on process priorities + + +The above problem of preventing the SIBO computer from auto-switching off is not the only potentially +deleterious side-effect of continuous activity. Just as continuous activity within Events4 prevents sys$null +receiving any CPU, so too will any other lower priority processes be locked out. + + +As it happens, Subproc and Events4 both run at the same process priority - the default of 0x80. (See the +chapter Building an Application for details on how process priorities are initialised.) However, suppose +the process priority of Subproc were lowered to say 0x70. In that case, continuous activity within Events4 +would mean that Subproc, although launched, would never receive any CPU. Thus Events4 would +perpetually display the message "Subp launched", but never the completion message "Subp slept xxx +ticks". + + +The solution here is that any process about to become computationally intensive over a long period of time +should consider lowering its process priority, say to 0x70 - using the call p_setpri. For some related +discussion, see the section on wStartCompute in the Window Server Reference manual. + + +5-14 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +The call p_ioyield + + +One more potentially surprising fact about continuous activity within a program ought to be mentioned. + + +Clearly, not every program needs to be structured with an asynchronous event processing loop as in the +Events programs. Whilst such a loop is undoubtedly the correct architecture for a larger program, other +simple programs may have alternative structures. + + +For example, Subproc makes no call to p_iowait - nor does it need to, being purely single-threaded. +Again, the example Plib programs discussed in the chapter Building an Application (eg p_hello, p_comp +and p_prndir) likewise survive without an asynchronous event processing loop, since they are likewise +single-threaded. + + +However, there may be a temptation for programs to use the following semi-asynchronous mechanism, in +order to be able to respond to keypresses (say) whilst being mainly dedicated to some continuous activity: + + +¢ continue processing queue an asynchronous request to receive a keypress +e start the continuous activity +e every so often, test to see if the status word is still z_F1LE_PENDING +e if it is, continue processing +In other words: + + +FOREVER + + +{ + +QueueSer (&keystat) ; + +while (keystat==E_FILE_PENDING) +MoreProcessing(); + +ProcessKey(); + + +} +However, this program may totally fail, with keystat never changing from B_FILE_PENDING. + + +The reason for this is rather complicated, but it is worth understanding. It has to do with what happens +when an asynchronous event completes. This completion often involves two distinct phases: + + +e the completion itself happens on an interrupt + + +¢ an interrupt service routine runs, and the i/o device changes some of its internal variables to +record this fact + + +e however, the i/o device generally cannot write to the associated status word during the interrupt +service routine itself + + +e this is because there are strict rules on what can and cannot be done within an interrupt service +routine (see the chapter Writing Device Drivers in the Additional System Information manual for +more details) + + +e instead, the i/o device relies upon its so-called wait handler routine to be called, so that it can +finish the job of completing the request - writing to the status word and signalling the application + + +e these wait handler routines only have an opportunity to run inside the call p_iowait (or +equivalent). + + +In other words, the description given earlier in this chapter of the functioning of p_iowait was incomplete +in one important respect: not only does this routine take note of the value of the i/o semaphore for the +application, and suspend the application so long as this remains negative; it also gives all i/o device +channels in the application an opportunity to run their wait handlers. + + +5-15 + + +GENERAL PROGRAMMING MANUAL + + +Accordingly, the earlier code has to be changed into + + +FOREVER + +{ + +QueueSer (&keystat) ; + +while (keystat==E_FILE_PENDING) +{ +MoreProcessing(); +p_iosignal(); +p_iowait (); +} + + +ProcessKey (); + + +} +which is in fact much more in line with the main routine of the Events4 application discussed. + + +For convenience, the single call p_ioyie1d can be used with the same effect as p_iosignal followed by + + +p_iowait. + + +Note incidentally that it is a rare application that needs to actually write a wait handler; there is of course +no need to write a wait handler routine just because an application involves asynchronous i/o. + + +General remarks + + +Multi-threadedness and multi-tasking + + +For the sake of clarity, the two different notions of multi-tasking and multi-threadedness ought to be +compared and contrasted: + + +e multi-tasking involves two (or more) different processes; multi-threadedness involves two (or +more) event sources within one process + + +e the operating system takes care of multi-tasking automatically, on behalf of applications; multi- +threadedness requires conscious effort from an application + + +e §=multi-tasking is pre-emptive in that a process with a higher priority that is ready to run will +always displace a lower priority process that is running + + +e multi-threadedness is non pre-emptive in that an event source with a higher priority has to wait +until a lower priority event source voluntarily gives up CPU, before being able to run. + + +Subprocess or idle object? + + +In the design of large systems, there is considerable scope for decision-making on whether to assign +compute-intensive tasks to idle objects within an application, or to a subprocess of the application proper. +Some factors that may be considered in making such a decision are: + + +e having two different processes automatically allows a total combined dataspace greater than 64k + + +e asubprocess need not worry unduly about creating "holes" ("fragmentation") in its allocator +heap, since these will all vanish when the subprocess terminates (when its entire heap vanishes); +however, if an idle object is transient and terminates well before the overall application finishes, +any fragmentation it creates in the allocator heap may have a more damaging long-term effect +(see the chapter Memory Allocation in the Plib Reference manual) + + +e an idle object is much more tightly bound to the main program than is a subprocess + + +¢ communications between a subprocess and the main program have to be much more formalised +than is the case with an idle object + + +e an idle object can draw to the same windows on the screen as the main application, but not so for +a subprocess (except in the case of the MC - see the function wAttachToclient in the Window +Server Reference manual). + + +5-16 + + +5 FUNDAMENTAL PROGRAMMING GUIDE-LINES + + +Window redraws as an event source + + +Up till now, one very important event source has not been mentioned in this chapter. This is the event of a +window requesting itself to be redrawn. (In fact, the request originates from the Window Server.) + + +These events do not occur when using console i/o, nor when using windows with back-up bitmaps: +windows are automatically redrawn by the Window Server in these cases. However, high quality +applications undertake window redrawing by themselves, so as to avoid the large ram overheads of the +back-up bitmaps. (See the Introduction chapter of the Window Server Reference manual.) + + +Such applications must remain responsive to redraw events at all times - otherwise their screen will +remain blank if they are suddenly task switched into foreground, or if an overlapping menu or dialog +window is removed. This is all the more reason for these applications to adopt the sort of general event +processing architecture outlined in this chapter. + + +The APPMAN and ACTIVE classes in OLIB + + +The appman and active classes in olib.dyl provide system support for object-oriented applications +e representing their event sources (each event source is represented by an "active object") +e prioritising these event sources +¢ maintaining active and status words for each event source +e calling p_iowait at appropriate times +e ensuring that all event sources are properly polled. + + +At the same time, the appman class ("appman" is short for "application manager") provides an automated +mechanism for error handling, as well as handling the interface to resource files (see the Resource Files +chapter in the Additional System Information manual). + + +These topics are further discussed in the Object Oriented Programming Guide. In addition, the appman +and active classes are documented in the OLIB Reference manual. + + +5-17 + + +GENERAL PROGRAMMING MANUAL + + +5-18 + + +CHAPTER 6 + + +CoPyY-PROTECTING SOFTWARE + + +Introduction + + +This chapter considers various mechanisms to "copy-protect" software written for SIBO computers. +Possible goals of copy-protection include: + +e software should be able to run, only from the original SSD it is supplied in + +e — software should be able to run, only on one particular computer + + +e first generation copies should be allowed, but not second generation copies (ie direct copies make +from the original SSD would run, but not copies of these copies) + + +e possibly, the number of first generation copies allowed could be limited. + + +These different goals vary in their applicability to the different computers in the SIBO range. For +example, software that disallowed even first generation copies would be very unwelcome on the Series 3, +because it prevents consolidation - the process whereby users copy more than one different application +onto the same SSD. It is unlikely that such software would sell at all well. On the other hand, this kind of +strict copy protection makes more sense for the HC, and for corporate ("Vertical") programs generally. + + +At the same time, software developers may wish to apply differing amounts of sophistication in their copy +protection schemes - some being willing merely to frustrate the casual would-be copier, and some being +determined not to allow copying at all (if possible). + + +This chapter does not favour one copy protection method over all others. Rather, it simply hints at various +different possibilities. Software developers may find it convenient to mix and match the different +proposals made, as well as others (along the same lines) that they can think of themselves. + + +By the very nature of the subject, too much documentation would be self-defeating. Once any algorithm to +implement copy protection becomes widely known, methods to defeat this algorithm may be developed +and circulated. + + +| ic I a +The free space method + + +This method aims at strict copy protection: the software will only run if it is on the original SSD. + + +This simple yet effective method turns one of the commonly debated ‘disadvantages’ of using Flash storage +into an advantage. + + +The method is based around the fact that when a file is deleted from a Flash SSD it remains on the pack +taking up space but is no longer practically accessible. Assuming that an application master pack contains +a deleted file, if someone were to copy this pack using the usual copy from the root including +subdirectories, the resulting copy of the master pack will differ fundamentally: the deleted file no longer +exists. This in turn means, rather conveniently, that the amount of free space on the pack will be different. + + +Given the above you can then hard-code into your application a check to see if the figure for space on the +pack matches the figure you expect: if it does then all well and good; else, do not allow the software to +run. + + +GENERAL PROGRAMMING MANUAL + + +The way to find the amount of free space on an SSD is to call p_dinfo. For example, a program that prints +the amount of free space on the disk the program was launched from: + + +#include +#include +#include + + +GLREF_D TEXT *DatCommandPtr; + + +GLDEF_C INT main(VOID) + + +{ +P_DINFO dinfo; + + +p_dinfo(DatCommandPtr, &édinfo) ; + +p_printf ("Free space is %lu",dinfo.free); +p_getch (); + +return (0); + + +} + + +First generation copying methods + + +Methods that allow first generation copies to run, but not second generation copies, rely on a separate +"AppCopy" program being provided on the master SSD, in addition to the program itself. + + +First generation copies can only be made using the AppCopy program. Copies made using ordinary Copy +commands will fail. Further, AppCopy will refuse to copy first generation copies into second generation +copies. + + +Essentially, AppCopy does not make an exact copy, but changes some of the bytes in the application +program. This can be done, even on Flash SSDs, provided: + + +e the original values of the bytes are all oxrft's + + +e the bytes are adjusted one at a time (assuming that a complete copy has already been made, and +that this complete copy has to be altered). + + +The last point is most important; the Flash filing system tests for the special case of only one byte being +written, and in this case, alters the physical byte on the SSD. In other cases, the physical structure of the +file is significantly changed. + + +Preserving checksums + + +Note that in adjusting bytes in a program file, care has to be taken not to disturb the code or data +checksums (as reported eg by the tool edump.exe). Otherwise, the operating system will refuse to run the +program, believing it to be corrupt. + + +The checksums can be preserved in either of two ways: +e provided enough bytes are changed, the checksum can be left the same as it was originally + + +e rather than changing the program part of the image file, one of the add-files inside the image file +should be changed (see the chapter Building an Application for details of add-files). + + +In general, the second method is preferable. +What kind of change should be made +The change made to the program file has two purposes: +e the file is now recognisably a first generation copy + + +e the change contains data somehow allowing this first generation copy to run, in a way preventing +a straight copy of this file from running on another computer. + + +Possible ideas on this second point include: + + +e information from an environment variable specially created on the target computer (secretly and +with a random value), by the AppCopy program + + +e the date the copy was made (so that the copy will "expire" after a certain length of time) + + +e details about the low-level structure of the SSD (see below). + + +6 COPY-PROTECTING SOFTWARE + + +To make the mechanism less obvious to a casual browser, any information from say an environment +variable ought to be stored in the file encrypted in some way. + + +Restricting the number of copies made + + +In order to restrict the number of first generation copies ever made to eight, say (which would not be +unreasonable), certain bytes in the master copy of the program could be changed. As above, these bytes +would start with the value oxf£, and would have to be written one at a time. + + +The documentation for the product would have to state clearly that AppCopy could only be used eight +times. This would have the effect of making the owner of the software most wary against making cavalier +bootleg copies. + + +This method will of course only work if the SSD containing the original copy can be written to. This will +be impossible for OTP (One Time Programmable) or masked ROM SSDs. In this case, information about +the number of first generation copies made could be stored in another environment variable, though of +course this method would be easier to subvert. + + +Low level SSD information + + +Each SSD contains a so-called "unique ID" which can be used to identify it. + + +Another potentially very useful piece of information would be the physical pack offset of the start of a +nominated file on an SSD. An AppCopy program could create a small file on the target SSD, and then +delete it, before copying the program file across. The physical pack offset of the start of the program file +could then be written into the program file (possibly in encrypted form), for the program to check when it +starts to run. + + +Alternatively, information could be read from the deleted file. + + +These types of information can be read by use of the p_locreadpda function, described in the Files +chapter of the PLIB Reference manual. + + +Copy-protection by changing the ROM + + +In the case of the HC, it is possible to use the tool romwrite.exe to overwrite portions of a file custom$.dat +in the ROM of the HC. See the chapter Introduction to the HC in the HC Programming Guide for details +of the operation of romwrite.exe. + + +Programs can then check that they are running on a given specified HC. + + +To read the contents of custom$.dat, just open the file as normal, specifying the full path name +rom: :custom$.dat. + + +One other possibility is to change the contents of the ROM more radically, eg placing certain software into +the ROM, with a program on an SSD refusing to run unless this software is present in the ROM. For more +details, again see the HC Programming Guide. + + +GENERAL PROGRAMMING MANUAL + + +6-4 + + +CHAPTER 7 + + +COMPATIBILITY + + +Introduction + + +The vast majority of existing software will, in principle, run on all machines in the SIBO range, provided +that the display can accommodate itself to the different screen sizes. + + +For details of the differences between SIBO machines see Writing Software for the HC in the HC +Programming Guide and the Series 3 family compatibility section of the Series 3 Programming Overview +chapter in the Series 3/3a Programming Guide manual. + + +What machine am I running on? + + +Most SIBO machines can be distinguished by their screen sizes, as determined by the return value from a +call to p_geticda. The possible return values for existing SIBO machines are as follows: + + +E_LCD_640_400 (0) +E_LCD_640_200_SMALL (1) +E_LCD_160_80 (4) +E_LCD_240_80 (5) +E_LCD_480_160 (11) +E_LCD_240_100 (12) +E_LCD_240_160 (14) + + +a 640x400 pixel display as on the MC 400 + +a 640x200 pixel display as on the MC 200 + +a 160x80 pixel display as on the HC + +a 240x80 pixel display as on the Series 3 + +a 480x160 pixel display as on the Series 3a and Series 3c +a 240x100 pixel display as on the Workabout + +a 240x160 pixel display, as on the Siena + + +This will distinguish all machines except the Series 3a and Series 3c, which have screens of the same size. +These two machines can be distinguished by means of a call to the function p_returnexpansionportinfo, +present in machines with EPOC version 3.90F or later, as in the following example code fragment. + + +GENERAL PROGRAMMING MANUAL + + +UINT lcdtype; +UINT version; +UINT port; + + +lcdtype=p_getlcd(); + +if (lcdtype==E_LCD_480_160) +{ /* S3a or S3c */ +version=p_version(); +if (version>=0x390F) + + +{ /* safe to call p_returnexpansionportinfo */ + + +port=p_returnexpansionportinfo() +if ((port & 0x0700)==0x0300) +{ +/* must be S3c */ +} +else +{ +/* must be S3a */ +} +} +else +{ +/* EPOC version less than 3.90, +} +else +{ +/* machine determined by LCD type */ +} + + +’ + + +so must be S3a */ + + +INDEX + + +.afl files + +add file lists, 3-13 + +add file lists - changing, 3-14 +.app files + +versus .img files, 3-13 +.dfl files + +add file lists for DYLs, 3-14 +.dyl files + +building with emake.exe, 3-14 +.img files + +applications, 3-1 + +control over, 3-12 + +creating, 3-3 + +versus .app files, 3-13 +Idd files + +building with emake.exe, 3-14 +.pdd files + +building with emake.exe, 3-14 +.pic files + +application icons, 3-13 +.pr files + +application project files, 3-1 + +project files - a first look, 3-2 +sc files + +resource files - application, 3-13 +zc files + +resource files compressed, 3-13 +.shd files + +shell data files, 3-13 +ACTIVE class + +remarks on OLIB, 5-16 +add file list + +application, 3-13 + +application - changing, 3-14 + +application DYLs, 3-14 +application + +a first look at .img files, 3-3 + +add file lists, 3-13 + +add file lists - changing, 3-14 + +add file lists for DYLs, 3-14 + +app files vs img files, 3-13 + +batch files - housekeeping, 3-6 + +building, 3-1 + +building - introduction, 3-1 + + +building - more complex example, 3-9 +building - more complex example PLIB, 3-9 + + +building - multi-file, 3-9 +building - with assembler, 3-11 +building emake.exe, 3-14 +building eremake.exe, 3-14 + + +copy protection see copy protection, 6-1 + + +debugging on SIBO system, 3-4 +file - control over, 3-12 +file transfer to SIBO system, 3-1, 3-3 +graphics and, 3-10 +heap size - minimum, 3-12 +Hwif - building, 3-10 +icon files, 3-13 +information from edump.exe, 3-12 +multi-tasking - remarks on, 5-16 +multi-threaded - remarks on, 5-16 +priority - control over, 3-12 +resource .rsc files, 3-13 +resource files .rzc compressed, 3-13 +running on SIBO system, 3-3 +shell data files, 3-13 +version number - control over, 3-12 +application development +C SDK equipment required, 3-1 +C SDK files for oop, 3-2 +C SDK files required, 3-2 +first example, 3-2 +fundamental guide-lines, 5-1 +applications +.img files, 3-1 +APPMAN class +remarks on OLIB, 5-16 +assembler +applications - containing, 3-11 +asynchronous I/O +programming, 5-2 +auto-switch-off +p_unmarka, 5-14 +SYS$NULL - chance to run, 5-14 +background processing +programming example, 5-2 +batch files +application housekeeping, 3-6 +compilation, 3-6 +compilation complications, 3-7 +build +C SDK configuration files, 3-11 + + +GENERAL PROGRAMMING MANUAL + + +building + + +C + + +applications, 3-1 + +applications - control over, 3-12 +applications - more complex example, 3-9 +applications - more complex example PLIB, +3-9 + +applications - multi-file, 3-9 + +applications - with assembler, 3-11 +applications introduction, 3-1 + +applications with graphics, 3-10 +applications with Hwif, 3-10 + + +manuals - Topspeed C, 2-1 + + +C SDK + + +C++ + + +build configuration files, 3-11 + +configuration file tscfg compiler, 3-11 +configuration file tsprj.txt, 3-11 + +configuring the redirection file, 1-3 +configuring the Topspeed project system, 1- +2 + + +directory structure, 1-2 +documentation version, 1-1 +equipment required, 3-1 +files required, 3-2 + +files required - oop, 3-2 +installation, 1-1 +installation phases, 1-1 +manuals, 2-1 + +manuals - where to start, 2-2 +overview SIBO system, 2-1 +professional version, 1-1 +SIBO software, 1-2 + +small model code, 1-1 +standard version, 1-1 +Topspeed C, 1-1 + +Topspeed software, 1-2 +variants of, 1-1 + + +object oriented programming and, 2-3 + + +cancelling timers + + +in general, 5-6 + + +Clarion Software + + +Topspeed C, 1-1 + + +CLIB + + +console device I/O, 4-3 + +DOS file names, 4-3 + +file handle conversion, 4-2 + +floating point emulator, 4-3 + +floating point emulator - panic 80, 4-3 +int86x implementation, 4-2 + +intr implementation, 4-2 + +library - building, 4-4 + +missing DOS functions, 4-1 + +notes on, 4-1 + + +CLIB & PLIB + + +contrasted, 3-4 + + +code size +application CLIB, 3-5 +application PLIB, 3-5 +compatibility +software on SIBO systems, 7-1 +compilation +batch file complications, 3-7 +batch files, 3-6 +optimisation warning, 3-11 +TSC vs TSCX, 3-8 +compute intensive application +CPU yielding, 5-13 +configuration file +C SDK tscfg compiler, 3-11 +C SDK tsprj.txt, 3-11 +configuration files +C SDK build, 3-11 +console device +implementation in CLIB, 4-3 +in general, 5-6 +cooperating applications +debugging, 5-11 +copy protection +first generation copy method, 6-2 +free space method, 6-1 +introduction, 6-1 +low level SSD method, 6-3 +mechanisms, 6-1 +ROM changing method, 6-3 +CPU intensive +yielding in applications, 5-13 +CPU yielding +compute intensive applications, 5-13 +programming, 5-2 +customised +libraries, 3-10 +debugging +applications - on SIBO system, 3-1, 3-4 +cooperating applications, 5-11 +serial port comms applications, 5-13 +device driver +LDD - building with emake.exe, 3-14 +PDD - building with emake.exe, 3-14 +devices +I/O in general, 5-5 +directory structure +C SDK, 1-2 +documentation +C SDK - where to start, 2-2 +documentation sources +programming, 5-1 +DOS functions +CLIB - missing functions, 4-1 +DYL +add file lists into application, 3-14 +building with emake.exe, 3-14 +dynamic library +DYL - building with emake.exe, 3-14 + + +edump.exe +application information, 3-12 +utility program, 3-12 +emake.exe +application building, 3-14 +application conversion, 3-1 +utility program, 3-14 +EPOC +explained, 2-2 +epocinit +project file statement, 3-6 +eremake.exe +application building, 3-14 +utility program, 3-14 +error handling +a first look, 5-7 +events and, 5-7 +resource tidying, 5-8 +errors +panic number ranges, 2-3 +panics explained, 2-3 +events +active and inactive sources, 5-12 +ACTIVE class - remarks on, 5-16 +APPMAN class - remarks on, 5-16 +idle objects, 5-14 +multiple source examples, 5-3 +p_iosignal - function of, 5-14 +prioritisation of sources, 5-5 +window redraw - remarks on, 5-16 +example code +detecting which SIBO system, 7-1 +fatal program errors +panics explained, 2-3 +file handle +conversion in CLIB, 4-2 +file names +DOS implementation in CLIB, 4-3 +file transfer +applications - to SIBO system, 3-1 +applications to SIBO system, 3-3 +floating point +emulator - panic 80 in CLIB, 4-3 +emulator in CLIB, 4-3 +fundamental guide-lines +programming, 5-1 +graphics +applications and, 3-10 +heap size +minimum, 3-12 +hello world +application - PLIB first example, 3-4 +application first example, 3-2 +Hwif +application building, 3-10 +I/O devices +in general, 5-5 + + +INDEX + + +icon files +application, 3-13 +IDE +Topspeed Integrated Development +Environment, 3-1 +idle object +contrasted with sub-process, 5-16 +idle objects +events, 5-14 +p_iosignal - function of, 5-14 +image file +control over, 3-12 +include file +stdepoc.h, 3-11 +installation +C SDK, 1-1 +int86x +implementation in CLIB, 4-2 +inter-process communications +in Events2 - and Subproc, 5-8 +mechanisms, 5-10 +intr +implementation in CLIB, 4-2 +IPCS +in Events2 - and Subproc, 5-8 +mechanisms, 5-10 +key presses +remarks on, 5-4 +keyboard input +programming example, 5-2 +LDD +building with emake.exe, 3-14 +libraries +customised, 3-10 +library +building CLIB, 4-4 +CLIB missing DOS functions, 4-1 +CLIB notes on, 4-1 +machine +detecting which SIBO system, 7-1 +manuals +C SDK, 2-1 +Topspeed, 2-1 +multi-tasking +applications - remarks on, 5-16 +multi-threaded +applications - remarks on, 5-16 +programming, 5-2 +object oriented programming +C++ and, 2-3 +Psion C approach, 2-3 +optimisation +compilation warning, 3-11 +p_hello.c +source code, 3-5 +p_iosignal +function of, 5-14 + + +iii + + +GENERAL PROGRAMMING MANUAL + + +p_iowait +remarks on, 5-4 +status words - declaring, 5-7 +status words - remarks on, 5-5 +p_ioyield +remarks on, 5-14 +p_tickle +function of, 5-13 +p_unmarka +auto-switch-off, 5-14 +panic 80 +floating point emulator - CLIB, 4-3 +panics +explained, 2-3 +number ranges, 2-3 +PC +C programs, 1-1 +PC based +development, 1-1 +PDD +building with emake.exe, 3-14 +PLIB +hello world application example, 3-4 +PLIB & CLIB +contrasted, 3-4 +priorities +processes - remarks on, 5-14 +priority +application - control over, 3-12 +process priorities +remarks on, 5-14 +program +file transfer to SIBO system, 3-3 +program errors +panics explained, 2-3 +program size +application CLIB, 3-5 +application PLIB, 3-5 +programming +asynchronous I/O, 5-2 +console device I/O in general, 5-6 +CPU yielding, 5-2 +documentation sources, 5-1 +error handling - a first look, 5-7 +error handling - in events, 5-7 +error handling - resource tidying, 5-8 +events - prioritisation of sources, 5-5 +events multiple source examples, 5-3 +example of background processing, 5-2 +example of keyboard input, 5-2 +example of serial port data input, 5-2 +example of sub-process completion, 5-2 +example of timer expiry, 5-2 +fundamental guide-lines, 5-1 +I/O devices in general, 5-5 +introduction - example source, 5-2 +introduction to, 5-1 +introduction to events - example apps, 5-2 + + +key presses - remarks on, 5-4 +multi-threaded, 5-2 +p_iowait - remarks on, 5-4 +p_iowait remarks on, 5-4 +p_iowait status words - declaring, 5-7 +p_iowait status words - remarks on, 5-5 +p_ioyield - remarks on, 5-14 +PC based development, 1-1 +semaphore I/O, 5-4 +timers cancelling in general, 5-6 +timers remarks on, 5-4 +user interface - simple examples, 5-2 +programs +.img files, 3-1 +project file +a first look at .pr files, 3-2 +advanced use, 3-11 +application project .pr files, 3-1 +epocinit statement, 3-6 +reusing - general, 3-6 +resource files +application .rsc files, 3-13 +application .rzc compressed, 3-13 +screen sizes +detecting which SIBO system, 7-1 +table of for SIBO systems, 7-1 +segment registers +small code model, 4-2 +semaphore +I/O remarks on, 5-4 +serial port +comms debugging, 5-13 +data reception of, 5-11 +opening, 5-12 +serial port data input +programming example, 5-2 +shell data files +application, 3-13 +SIBO +explained, 2-2 +systems family, 1-1 +SIBO SDK +see C SDK, 2-1 +SIBO systems +screen size table, 7-1 +software compatibility, 7-1 +what machine, 7-1 +small code model +segment registers, 4-2 +small model code +C SDK, 1-1 +software +compatibility across SIBO systems, 7-1 +copy protection introduction, 6-1 +copy protection mechanism, 6-1 +stack size +default, 3-6 +specifying, 3-6 + + +INDEX + + +status words + +declaring - p_iowait, 5-7 +stdepoc.h + +include file, 3-11 +sub-process + +contrasted with idle object, 5-16 +sub-process completion + +programming example, 5-2 +SYS$NULL + +chance to run auto-switch-off, 5-14 +timer expiry + +programming example, 5-2 +timers + +cancelling in general, 5-6 + +remarks on, 5-4 +Topspeed + +Integrated Development Environment, 3-1 +Topspeed C + +Clarion Software, 1-1 + +library reference, 2-1 + +package, 1-1 +ts.red file + +C SDK redirection file, 1-3 +TSC vs TSCX + +contrasted, 3-8 +tscfg + +configuration file compiler, 3-11 +tsprj.txt + +configuration file, 3-11 +user interface + +programming examples, 5-2 +utility program + +edump.exe, 3-12 + +emake.exe, 3-14 + +eremake.exe, 3-14 +version number + +application - control over, 3-12 +versions + +C SDK, 1-1 +what machine + +detecting the SIBO system, 7-1 +window redraw + +event source - remarks on, 5-16 +window server + +WLIB library introduction, 3-5 +WLIB + +introduction, 3-5 +yielding CPU + +programming, 5-2 + + diff --git a/docs/1-02 HC Programming Guide 2.30_djvu.txt b/docs/1-02 HC Programming Guide 2.30_djvu.txt new file mode 100755 index 0000000..acdbcba --- /dev/null +++ b/docs/1-02 HC Programming Guide 2.30_djvu.txt @@ -0,0 +1,8565 @@ +SIBO 'C' Software Development Kit + + +HC 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 Introduction to the HC............cccsssssssscssscrsssrssersecersserssessessessesssesssssssssseessessessssssssseseesseeeses 1-1 +Phe ‘AC: concept sssitiavastesipiist asaya La a aie et seek a 1-1 +SWitChiiM OMA OLE seo: 5.2) sug cant ete sk aust sees bet aek Vound oat beeteds weet avn, Hag ace (See sane buted taet ane 1-1 +Switching on for the first t1Me........ cele eeseceseeceseeeesseecsseecsseecsseeceseeeesseessaeesseeeees 1-1 +PHS Basic hardware’: .vse.ceessoeseces folecedetehedsesvchesepsdetvekesaeh odes sted itt seehedepetet eathawl deseten ete easbedey 1-2 +PLOCOSSON oie eceeediseeates big teesedS phase sindess cb steabemiade ech phebbesiodusbinpha degipanee oh Gehh: 1-2 +Intertial Memory vee cee eckstest cen piiaees unt cana biodowes tinh ccnethebotss burke eeutaeteast List sen. toubaant iacteeensvs 1-2 +Solid state:disks (SSDS) jis.ces.ssesecessees cosesesvccssetes cose susvecsncevoossecuevagaeedeeessh cust cesesvovevancees 1-2 +EYP€S*OF SSD a. salar etic: Aetectivedetan esegaeeu tee sin Die a det astra eeatl Meade esata data aterratetes 1-2 +Expanision modules: s:..c2.2.e:.sitesiededeiyesibedi gies) ea oehbeipdeed deveined pone Gaede beeepdeed dae 1-3 +The Fast Serial port and the Cradle 0.0.0... cee eeeeeeseecsseeceseeeeseeeesaeecsaeessaeesseeesseeeesaes 1-3 +Power SUPPLY 4. ccs elie iodo tsaces detente ices As reee aaev ewe eee aia vse Mas even 1-4 +Caution regarding lithium batteries... eee eeeeeeseeesneeceneeceeeceseesesaeecsaeessaeesseeeeee 1-4 +SCLESN art ey tte he cdste breed ahistetadesteh ade temade veh eievemydanhodaterdene phatase 1-4 +WS yDOALC .o Abu Sete tse te tiies cet cae cake tat dee alte cauetnek ah ah react cas Rion tact cat ai ove tee 1-5 +THe ‘basic sottwarte iv. siiraiaticet aisianinia is eras ates cen gits len savaine bi limeaganeieiies 1-5 +Versions of the HC software ........ceeeescceseccesseecsseecseecsseecesaeeesaeecsaeecseecsseeeesaeessaeers 1-6 +The terms Epoc and Plib explained .......... ee eeeeeeseecescecsseeeeseeeeeseecsaeesseecsneeeesaeeesaes 1-6 +Graphics Window S€rVer ..........essccsesecssceceseceesececsseecsseeceseecesaeeesaeecsaeecsseeceseeeesaeersaeers 1-6 +Multi-taskine kernel .2...sés2inhvhii nial vale inne dine aii 1-6 +Support for asynchronous 1/0..........ceesecesseeceseecsseeceseeeesseecsaeecseecsseeeesaeeesaeesseessneeeees 1-7 +Database support fUNCtIONS.............cceeeeecceeeesceeeeseneeecseeeeeeseneeeeessaeeeeeenaeeeeneneeeeeeeaeeees® 1-7 +Support for remote file ACCESS ......... ees eeseeceseeesseeceseeeesseecsaeecseeceseecesaeeesaeessaeesseeene 1-8 +Other ROM-based library services ..........eseceeesessseessseecsseeceseeeesaeecsaeesseessseesesaeessaeers 1-8 +Other: ROM Components rey.cc. ea. cu.cevepssnsedep steceds padetbeey latch posuteds pode ses sndes ode y wdebeveveanseae. 1-9 +Customising’ an HG. sissies ee agi Sail ahi anal Gail Gained ani 1-9 +Hardware Customisation ............:cccesecceseccescecsseecseeceseecesaeeecescecesaeessseeesseecsseeceseeeesaes 1-9 +Replacing the built-in Shell oo... eee eeeeeesseccsseecsseecssceceseeceseeeesseecsaeecseesseeseseeeesaes 1-10 +Resettins, the: AG 12. cscccetdetocegaseteceesestech pinh eibsestetey pdnhewitaedesotet osthatetedesetebantpetsteterets 1-10 +Reproins the-AC 333.3 acsesiniiease ghsieltespaess Gigies eros Bigha eeovheibedapie anes hepae eens 1-11 +Master SSDs and mastcpy ...........ceeeccesscecesseceeeecsseecseessseecesaeeesseecsaeecsseeceseeeesaeessaeers 1-12 +Once-off ROM customisation Using ROMWTiItC...........eeeesesecsseceseecsneeseneeeesaeeesaeeaes 1-12 +Customisation for COPy-ProtectiON ..........escesseccsseeceeeeeseceeseeeesaeecsacecseeeeessseesesaeeesaes 1-12 +Connecting to other COMPULETS ........ eee eeeeeeseeeeseecsseeceseecesaeeesaeeeceseecesaeessaeecseessneeeeteeeesaes 1-13 +Basics of serial connections to an HC 00.0... eee eeeeeeeeeseeceesseeesaeecsaeecsseecneeesseeesseeeesaes 1-13 +RS232) CONNECTIONS 35305 iieeedipsapieele ease hl nelaaebd tii mavnie di die adae airy 1-13 +Summary of straightforward usage of Link on the HC .00.... eee eeeeeeseeeseeeeneeeeeeeeeeees 1-13 +Why not MS-DOS? racist eniiin ipsa deseyhenela spas ea eek sacs Bnd esp duns Chareeh ess dane SMepeesyeipaas 1-14 +2 Writing Software for the HC ................scccsssscssssssccsscssesssscseesssseessscsssssssesessssscsssscseessssssessoees 2-1 +Basic programming ChOICES............cccsscccesscceeeeneeeeeseaceceeeacecseeeeceecaeeeeeeeeeesereeseeneeeesseneeeess 2-1 +Choice of programming language...........eeeesececcsseessseecsseeessaeeesaeesaeecsaeecsseeeseeeeseeens 2-1 +Standard C (Clib) or Psion C (PLD) oo... cccsscccccccesssssneeeeececeseeeeeeeesseesssaeeeseeeesaes 2-1 +Writing the User 1Nterface occ: ccc. cio eevee ave ne Bie eucses saved oeesatue cea cousa outecsesudaccecoushecevvuntees 2-2 +Synchronous or aSynchronous Processing ..........ssecceseesseeceseeessneecseesseeseecsseeeeseeeesaee 2-3 +Example programs. ses: ca. divacdesevcuorssocunctohscsscnsccotsedentns oats bees evoouny odes auussdnheats even voneasetesbovteeday 2-4 +A graphics version of Hello World .0..........cccccccesesscceeesnceeceseeeeeeeeeeeesaeeeeesnaeensnneeeenees 2-4 +The: Gauge: appl Cation 25 cbse sack. iks ode oh one eis coe ek cake ahd vent nsteet oat + + +int main (void) +{ +puts ("Hello world"); +getchar(); +return (0); + + +} +together with a project file simple.pr + + +#system epoc img +#model small jpi +#compile simple.c +#link simple + + +will run on an HC without any difficulty whatsoever (see the chapter Building an Application in the +General Programming Manual for further discussion of TopSpeed .pr project files and their usage). + + +HC PROGRAMMING GUIDE + + +However, it is recommended that HC programmers rewrite the above program as follows: + + +#include +#include + + +int main(void) +{ +p_puts ("Hello world"); +p_getch (); +return (0); + + +} +with the project file changed to + + +#system epoc img +#set epocinit=iplib +#model small jpi +#compile simple.c +#link simple + + +The latter is said to be the "Plib" version of the former, which is a "Clib" program (the "P" of "Plib" stands +for "Psion"). + + +The following differences will be noticed between the two programs: +e the Plib program uses Psion-proprietary header files. +e the Plib program uses Psion-proprietary function calls (p_xxx functions). + + +e the Plib program links with a different library (this is the significance of the epocinit line in the +project file). + + +Code written with Plib calls is considerably more compact than code written with Clib calls. For example +the image file for the example Plib program (see above) has size 576 bytes compared with the image file +for the equivalent Clib program that has size 4480 bytes - an increase in size of almost seven hundred per +cent. + + +The reason for the greater compactness of compiled Plib code is that Plib functions provide only very thin +shells for functionality already present in the HC's ROM. Thus Plib calls make more efficient use of the +HC ROM software than do the equivalent Clib calls. Being tailored to the particular needs of computers +like the HC, Plib evolved with very different constraints and objectives from standard C libraries. In many +cases, Plib functions can be claimed to "improve" upon the specification of their nearest Clib equivalents. + + +The use of Plib calls does not always lead to such large space savings as seen in the example programs +(see above) - the reduction in the size of the compiled code depends on the number and types of library +function calls made. + + +Sometimes it will be desirable to write an application using both Clib and Plib calls simply because this +can ease the process of converting large programs to run on the Sibosdk system. The reduced development +time will thus outweigh the disadvantages of using the Clib calls. + + +However it is recommended that an application use the Plib library for at least some of its function calls. +Although it takes time to become familiar with the Plib library this will repay itself in the form of more +compact and powerful applications. Furthermore use of Plib functions is essential for accessing many +features of the Sibosdk ROM software - the enhanced graphics facilities of the Window Server for +example. + + +Writing the user interface + + +A SIBO interface can be written in one of the following ways: + + +e using console service functions such as p_printf, p_get1, and p_puts or their Clib equivalents. +These functions can only produce simple graphical output. They can be extremely useful when +debugging an application. + + +e using functions in the Window Server library with the contents of each window backed up with a +bitmap. This method is capable of producing a high quality graphical display. + + +e using functions in the Window Server library with the contents of each window explicitly +redrawn. This method is capable of creating a high quality graphical display. Use of window +redraws is more efficient than use of bitmap backups. + + +2 WRITING SOFTWARE FOR THE HC + + +The applications programmer does not have to learn to write applications that use the window redrawing +mechanism: for many applications backing up the window with a bitmap is sufficient (the penalties of +windows with backup bitmaps are much less on the HC screen than on the larger screens of some of the +other SIBO computers). + + +The applications programmer who subsequently goes on to learn about window redrawing will not have +wasted his/her time learning about window bitmap backups. The latter provide an excellent foundation for +the more complex concepts behind window redrawing. + + +The best way to learn graphics programming on the HC is probably to follow the example programs at the +end of this chapter and then extend and modify their function. For example one of the example programs +illustrates the use of the wInfomsg and wSetBusyMsg functions. These powerful graphics functions display +an information message and a flashing busy message respectively at the bottom right corner of the screen. +They are hardly more difficult to use than simple console functions such as p_printé and p_puts. +Working out how this program and the others work will help to familiarise you with the more commonly +used Window Server calls. + + +The example programs and the discussion in this chapter should provide the would-be HC applications +programmer with a sufficiently sound base to enable him/her to make effective use of the Window Server +Reference manual. + + +Synchronous or asynchronous processing + + +There is a class of programs in which all input to a program comes via the keyboard. These programs can +be schematised as follows: + + +Initialise(); + +FOREVER +{ +ReadKeyFromKeyboard() ; +ProcessKey (); + + +} + + +The program terminates in response to a certain pre-defined key. Whilst waiting for a key from the +keyboard, the program "hangs", i.e. it is unresponsive to other sources of input. In this case the hanging of +the program does not matter as there are no other sources of input. + + +The call ReadkeyFromKeyboard makes what is known as a synchronous read for a key; it is synchronous +becomes it does not return until the key it is waiting for has been delivered: the return of the call making +the request is automatically synchronised with the delivery of the key. + + +Consider another example of synchronous i/o. In this case, a program that is printing data might be +structured (at least in part) as follows: + + +Initialise(); + +FOREVER +{ +PrepareLineToPrint (); +SendLineToPrinter (); + + +} + + +This program loop terminates when there is no more data to print. Now the process of sending a line of +data to the printer might take some time. The printer buffer could be full in which case the program would +have to wait for the buffer to empty a bit before being able to prepare the next line for printing. Thus the +call sendLineToPrinter could be synchronous (this is the way beginner programmers would tend to write +the code), with the program "hanging" in the call until the printer has removed the data passed to it by the +program. In this state, the program is, again, unresponsive to other sources of input. + + +In either of the above examples, a simple extension of the code would require the synchronous call to +become asynchronous. The printing program could and should be extended to allow the user to terminate +the printing while in progress by simply pressing a predefined key. The key-processing program could be +extended so as to respond to a timer expiring (for example a signal to commence a backup procedure). + + +Many programmers approach this kind of generalisation in an ad hoc manner resulting in spaghetti like +code that is hard to debug, hard to maintain and hard to extend. + + +Such code will usually force the user to wait while it is waiting for one or more events. The user can thus +be shut out for significant periods of time. + + +2-3 + + +HC PROGRAMMING GUIDE + + +The software on the HC has been explicitly designed to address these issues. For all but the simplest of +programs the concept of asynchronous events is central to successful programming on the HC: would-be +applications writers are strongly urged to face up to this issue squarely, from the beginning. + + +This may sound daunting (and it probably would be daunting, on alternative software platforms), but for +two reasons, it is not: + + +e the HC operating system software has carefully isolated the various components involved in +asynchronous i/o: signals, semaphores, "status words", and "active words" (amongst others) + + +e example programs in the Fundamental Programming Guidelines chapter of the General +Programming Manual survey these components in a thorough yet straightforward manner. + + +Example programs + + +There are example programs scattered throughout the length and breadth of the SDK. It is recommended +that, whenever possible, would-be HC applications developers should take the time to try out these +examples, and to modify them. As in all fields, practice makes perfect - and it is always possible to get an +idea from the detail of one of these programs, which will prove helpful in a quite different coding +situation. + + +The three programs to be discussed in this chapter have particular relevance to the HC. They demonstrate +its graphics potential, and show how to create line editors to allow convenient data entry by end users of +the HC (whereas Series3 and Series3a programmers can use the Hwif library to obtain easy access to line +editors and other related user interface objects, there is at the time of writing no corresponding library for +the HC - so programmers have to take care of the user interface by themselves). + + +These examples build on those discussed in the General Programming Manual, and it is suggested that +any readers who have not yet worked through that manual carefully should do so now, before proceeding +any further. + + +In contrast with the examples in the General Programming Manual, which only use console i/o, the +example programs in this chapter all interact more directly with the Window Server. + + +The source code for all these examples is located in \sibosdk\demo. Incidentally, these programs can also +be made to run, with minor modifications, on Series3 and Series 3a machines. + + +A graphics version of Hello World +The first example is a short program stored as w_hello.c: + + +#include +#include + + +GLDEF_C INT main(VOID) +{ +WS_EV event; + + +wStartup(); + +gBorder (W_BORD_CORNER_4) ; + +wSetBusyMsg ("Hello world",W_CORNER_BOTTOM_LEFT) ; +do + + +{ + +wGetEventWait (&event) ; + +} while (event.type!=WM_KEY || event.p.key.keycode!=W_KEY_ESCAPE) ; +return(0); + + +} + + +The call wstartup takes care of routine preparation to interact with the Window Server (see the Window +Server Reference manual for more details of all of these calls). + + +The call gBorder draws a pleasant curved border around the edge of the screen. Vary the flags passed to +gBorder for different types of curves. + + +The call wSetBusyMsg displays the specified message flashing, at the nominated corner of the screen. In +general, the message will continue to flash, without any assistance from the application, until such time as +a call such as wcancelBusyMsg is made. + + +2-4 + + +2 WRITING SOFTWARE FOR THE HC + + +The call wcetEventwWait is a synchronous request to receive an event from the Window Server. These +events include notification of coming into foreground or background, as well as keypresses and requests to +redraw portions of the screen (these latter events are used by applications that explicitly handle window +redraws - such applications do not use the wStartup function and instead use the lower level function). + + +AS wGetEventWait is synchronous, it does not return until there is an event for the application to process. +In this example, the application is uninterested in any events other than keypresses, and even then, only +the ESC keypress is of interest. + + +In order to build w_hello, simply type make w_hello when in the appropriate source directory +(\sibosdk\demo). + + +The Gauge application + + +The Gauge application is altogether more sophisticated than w_hello: +e the screen display contains text in various font styles. + + +e the screen also contains a "growing scrollbar" or "petrol gauge" display item, whose content +grows regularly, as a timer beats. + + +e the speed at which the timer beats can be adjusted by keypresses from the user. +e the user can also reset the gauge display at will. + + +e the range of options open to the user is displayed on a range of "buttons", which momentarily +highlight whenever they are selected. + + +e in programming terms, a timer channel is created as a second event source. +e the synchronous wGetEventWait call is replaced by the asynchronous version wGetEvent. +The schematic form of main in gauge.c is as follows: + + +GLDEF_C VOID main(VOID) +{ +WS_EV event; +WORD wactive; + + +wStartup(); +INITIALISE(); +QueueTimer (); +wactive=FALSE; +FOREVER +{ +if (wactive) +wF lush () ; +else +{ +wGetEvent (&event) ; +wactive=TRUE; +} +p_iowait (); +if (event .type==E_FILE_PENDING) +{ +PROCESS_TIMER_EVENT () ; +QueueTimer (); +continue; +} +wactive=FALSE; +if (event .type==WM_KEY) +{ +switch (event.p.key.keycode) +{ + + +} + + +2-5 + + +HC PROGRAMMING GUIDE + + +The use of a little imagination will make it clear that this is the same basic architecture (albeit rearranged) +as in the Events programs discussed in the General Programming Manual: + + +e the variable wact ive is the active word for the Window Server event source + + +e the status word for the Window Server event source is built into the ws_zv struct passed to the +call wGetEvent: it is the event .type field + + +e there is no test on the timer status word, timstat, since if the call to p_iowait has returned and +event .type is still equal to E_FILE_PENDING, it can only be the timer which has an event to +deliver (given that there are only two event sources in the application). + + +The need to flush the Window Server buffer + + +Note the special test on wact ive at the top of the event loop in main. If wactive is still TRUE, it means +there is no need to call wGetEvent again (and in fact the application would be panicked if it did so). +However, it is necessary, in this case, to call wFlush, to ensure that the Window Server function buffer is +flushed out. Otherwise drawing calls could remain in this buffer all the time that the application is +suspended, inside p_iowait. + + +The point here is that, for efficiency (minimising IPC - InterProcess Communication - traffic between the +application and the Window Server), many Window Server functions are not implemented immediately: +rather, they are stored in a buffer which is only "flushed" every so often. See the Window Server Reference +manual for full details. + + +Another instance in the Gauge application where wFlush is called is in the routine Flash, in which a +highlight is momentarily displayed over a "button" containing the choice the user has just selected: + + +{ +P_EXTENT ext; + + +gInvObloid(&ext) ; +wFlush (); + +p_sleep (2); +gInvObloid(&ext) ; +} + + +Other graphics calls in Gauge + + +The contents of gauge.c can usefully be studied (eg use the SIBO Debugger while the program is running) +for examples of the following graphics function calls: + + +gPrintBoxText useful for "flicker free" drawing of text. + +gSetGc allows a change in the font or font style (and more besides) used to draw text. +gClrRect clears or highlights a given rectangle. + +gFillPattern applies a pattern (here, a "grey" pattern) to an area. + +gTextWidth calculates the width of a string of text. + +gInvObloid allows special "rounded" or "obloid-shaped" inverse videoing. + +gBorderRect draws any of a variety of curves around the edge of a specified rectangle. + + +A suite of line editor functions + + +The application LinEd demonstrates the use of a suite of line editor functions: three line editors are +created on the screen, each with text that the user can edit. The user chooses which entry to edit at any +one time by using the UP and DOWN cursor keys. Other editing keys have the expected effects on the +editors: + + +¢ typing printable characters enters these characters into the current string (with any existing +highlighted selection in the string being deleted). + + +e the editor beeps if it has already grown to its maximum size. + + +e the editor scrolls horizontally if there are more characters to display than can fit in the width +allocated to it on the screen. + + +2-6 + + +2 WRITING SOFTWARE FOR THE HC + + +e the DEL key deletes the character to the left of the cursor, whereas SHIFT+DEL deletes the +character to the right of the cursor, PSION+DEL deletes to the end of the line. + + +@ PSION+LEFT and PSION+RIGHT "home" and "end" the cursor, respectively, LEFT and RIGHT just +move the cursor one position. + + +The suite of "lined" (line editor) functions should be independently useful, either in their present form, or +modified for particular purposes (the lined functions are as they stand fairly general). From a broader +perspective, the lined functions demonstrate the creation of a user interface for applications on the HC. + + +The code in lined.c divides into two parts: the implementation of the lined functions, and the testing of +these functions. The main routine of the test program is worth considering in full: + + +GLDEF_C VOID main(VOID) +{ +LINED *ed[3]; +INT which; +WS_EV event; +INT keycode; + + +wStartup(); +gBorder (W_BORD_CORNER_4) ; +ed[0]=CreateLined(10, "One", TRUE) ; +ed[1]=CreateLined (30, "Two", FALSE) ; +ed[2]=CreateLined (50, "Three", FALSE) ; +which=0; +FOREVER + +{ + +do + +{ + +wGetEventWait (&event) ; + +} while (event.type!=WM_KEY) ; +keycode=event.p.key.keycodeé& (~W_SPECIAL_KEY) ; +switch (keycode) + +{ +case W_KEY_ESCAPE: + +if (event.p.key.modifiers==W_PSION_MODIFIER) + +p_exit (0); +case W_KEY_UP: +if (which) +{ +le_emphasise (ed[which--],FALSE) ; +le_emphasise (ed[which], TRUE) ; +} + +break; +case W_KEY_DOWN: + +if (which<2) + +{ + +le_emphasise (ed[which++],FALSE) ; +le_emphasise (ed[which], TRUE) ; + +} + +break; +default: + +le_key (ed[which], keycode, event.p.key.modifiers) ; + +} + + +} + + +The array of three pointers ea[3] is used to hold the "handles" of the three lined objects created. This +creation is done inside the call createLinea (further discussed below). At any one time, only one of these +three editors is "active" - displaying a flashing cursor and receiving editing keys from the user. The +application uses the variable which to keep track of the current active editor. + + +On receipt of an UP or DOWN key, the application changes its record of which editor is active. At the same +time, the editors themselves have to be informed of this change - so that they can adjust their appearance. +This is the role of the calls to 1e_emphasise. + + +All other keys (apart from PSION+ESC, which exits the application) are passed straight through to the +current editor, using the call 1e_key. + + +2-7 + + +HC PROGRAMMING GUIDE + + +Full specification of the lined functions + + +The routine 1e_init creates and initialises a lined object, according to the data in an IN_LINED struct +passed. This creation involves two separate allocator calls - one for the control block of the editor itself, +and one for the buffer to hold the string of text to be edited. Note that either of these calls can fail - in +which case the failure is reported back to the caller. The test application in Jined.c ignores this possibility, +under the rationale that the minimum heap of the application guarantees that these calls, made during +program initialisation, will always succeed. + + +The call either returns NULL, in the case of an alloc failure, or the handle to be used to identify this +particular editor in all subsequent 1e_xxx calls. + + +The meanings of the fields in the interface struct IN_LINED (defined in /ined.h) are as follows: + + +maxchars the maximum length of text that can be edited. + +winid the id of the window in which the editor is to appear. + +xoff the x-offset from the origin of the window to the top left of the editor (in +pixels). + +yofft the y-offset from the origin of the window to the top left of the editor (in +pixels). + +width the width of the editor (in pixels). + +height the height of the editor (in pixels). + +asc the distance (in pixels) between the top of the editor and the base line of the + + +text edited. + + +font the identifier of the font used to display the text. +style the style of the font used to display the text. +autoselect TRUE to automatically select the entirety of any text set into the editor by the + + +calling program, FALSE to leave such text un-selected. +Note how these fields are set up in the routine createLined: + + +LOCAL_C LINED *CreateLined(INT yoff,TEXT *msg, INT emph) +{ +IN_LINED init; +LINED *ed; + + +init.maxchars=20; +init.winid=wMainWid; +init.xoff=10; +init.yoff=yoff; +init.width=80; +init.height=10; +init.asc=8; + +init. font=WS_FONT_BASE+4; +init.style=0; +init.autoselect=TRUE; +ed=le_init (&init); +le_set_text (ed, p_slen(msg) ,msg) ; +le_emphasise (ed, emph) ; +le_visible (ed, TRUE) ; +return (ed) ; + + +} +The static wMainwWid is one that is set up by the call wstartup. See the Window Server Reference manual. + + +The initial text of the editor is set in by a call 1e_set_text made after the call to 1e_init, but before the +call to le_visible which causes the editor to actually be drawn. Also in between the 1e_init and +le_visible calls is a call to 1le_emphasise to specify whether the editor should be displaying a flashing +cursor (and also whether any selected region should be visibly highlighted). + + +Another call that could be made between 1e_init and le_visible is le_set_cwidth, to change the width +of the flashing cursor from its default (which is two pixels wide). + + +2-8 + + +2 WRITING SOFTWARE FOR THE HC + + +As noted above, the way the application sets text into a lined object is with the call 1e_set_text. In this +implementation, the application is required to specify the length of the string as a parameter to +le_set_text - le there is no requirement to pass the string in zero-terminated form. + + +On the other hand, the editor itself maintains the string, as it is edited, in zero terminated form - which +may be convenient for the application. + + +The way the application can "sense" the contents of the string, as edited by the user, is simply to read this +string out from the data maintained by the lined object. For this purpose, the form of the L1NeEp struct +needs to be known. This struct is defined in lined.h. Needless to say, most parts of the data in this struct +are strictly read-only. If an application writes directly into this data, random problems can ensue later. + + +If a lined object is no longer needed, all the memory it uses can be freed by calling 1e_dest roy. Be sure to +have an independent copy of the string edited, before making this call. + + +Finally, the function 1e_visible, as well as initially making the editor visible, can also be used at some +later stage to "hide" the editor again, if desired. + + +General comments + + +Device drivers for the HC + + +Note that the i/o Devices Reference manual gives details of how to program many of the peripherals that +can be attached to an HC: + + +a parallel port. + +a serial port (including xmodem and ymodem file transfer). +a magnetic card reader. + +a bar code reader. + +a modem. + + +The chapter The HC in the Cradle, later in this manual, gives details of the operation of the HC when +located in a cradle. + + +Writing a customised shell process + + +The System startup section of the Introduction chapter of the Window Server Reference manual gives two + +examples of possible small alternative shell programs. The source for one of these, /kshell.c, may be found +in \sibosdk\demo. As well as presenting the source, this section of the SDK raises various issues to do with +replacing the built-in shell program with a customised one. + + +In case it is desired to create a shell process with functionality intermediate between /kshell and corpshil +(which is the Command Shell), see the documentation, later in this manual, of each keyword supported by +the Command Shell, for a reference to the C functions used to implement that keyword. + + +Developing applications on restricted-keyboard HCs + + +Developers writing for HCs with restricted keyboards lacking a full set of alphabetic keys face the problem +that many commands that might ordinarily be typed into an HC during the course of program +development - for example, file or SSD management commands in the HC Command Shell - simply +cannot be typed into the HC, on account of the required alphabetic keys not being present on the keyboard. + + +In practice, preliminary development would probably be done using a different HC, with a fuller +complement of keys. The program being developed would only be transferred to the restricted-keyboard +HC at a later stage of development. However, the problem recurs at this later stage. + + +The comprehensive solution to this problem involves one of the fundamental principles of the HC - its +interconnectability with other computers. Briefly, rather than the HC being controlled from its own +keyboard, it can be controlled from a remote keyboard, say that of a PC. The commands are transmitted to +the HC via one or other form of serial connection. + + +See the chapter HC Command Sheil for more details of this mechanism. + + +2-9 + + +HC PROGRAMMING GUIDE + + +2-10 + + +CHAPTER 3 + + +HC COMMAND SHELL + + +Overview + + +The HC Command Shell provides a MS-DOS like utility for functions that can be executed from a +command line. The range of functionality covered includes file and SSD management, program +management, information requests, and HC configuration. + + +Commands can be entered by typing at the HC command line in response to a $ prompt. Alternatively, +commands can be entered remotely, by typing at the terminal of a PC connected to the HC. + + +The HC will run batch files consisting of a sequence of commands. Batch files can be run in either of the +above modes. + + +Batch file processing + + +Epoc batch files are plain text files consisting of a series of commands. Each command has a line to itself. +By default batch files have extension . btf: + + +To invoke a batch file with name backup.btf, type @backup at the Command Shell s prompt. If necessary +specify the full path of the batch file. Thus + + +@loc::b:\batch\backup +or +@rem::c:\hc\devp\restore.bat + + +would both invoke batch files. In the first case the file is assumed to have a .btf extension. In the second +case the file extension is specified to be .bat. + + +Batch files can also call other batch files, and so on, up to eight levels deep. + + +Batch files are executed synchronously, i.e. no additional commands can be typed into a Command Shell +until any batch files it is executing have completed. + + +Whilst batch files significantly enhance the utility of the HC Command Shell they do have some notable +limitations: + + +e they cannot have parameters passed to them. +e they cannot contain conditional statements, such as if ... goto ... + + +These limitations can be got round by replacing the batch file with a program written in Opl, or in another +high level language such as C. + + +Launching programs + + +The Command Shell can be used to launch both batch files and programs (either Epoc executables or OPL +programs). + + +Epoc executables and OPL programs are run by simply typing their name without any additional prefix +(except possibly for an « - see below). + + +3-1 + + +HC PROGRAMMING GUIDE + + +When the following line is entered at the Command Shell +dojob + + +the HC will attempt to locate the corresponding command or file. The HC will execute this command or +file when and if it is found. The search is carried out as follows: + + +the HC checks that there is no internal command with the name dojob + + +the HC looks for a file dojob.opo in the current directory +e the HC looks for a file dojob.opo on a:, b:, and m: (in the order given) + + +e the HC looks for a file dojob.img, first in the current directory, then (as above) on drives a-, b:, +and m., and then in rom:: + + +e the HC looks along the same search path for a file dojob.app. + + +The search terminates once the command or file is found. Note that a file dojob.opo will be found in +preference to a file dojob.img. + + +To ensure that a file dojob.img is run, enter the extension explicitly: +dojob.img + + +Programs are assumed to be Epoc executables unless they have the extension .opo, in which case they are +assumed to be translated Op! programs. + + +Additional parameters can be passed to these programs. For example, +dojob b: +Synchronous programs and asynchronous programs + + +In contrast to batch files, which are always run synchronously (see above), programs can be run either +synchronously or asynchronously thus exploiting the multi-tasking capabilities of the HC. + + +By default, programs are launched asynchronously. This means that while the program is executing, the +user can task back to the Command Shell and continue to issue other commands. + + +When the program is started, it will by default (assuming it has a user interface) take over the foreground +screen. To access the Command Shell, or indeed any other tasks that may be running on the HC at the +time, press TASK as many times as is required. Every time TASK is pressed, a different program cycles into +foreground. + + +Note that there is no need to quit the foreground program in order to start another - start a new program +by pressing the TASK key until you get into the Command Shell, then type the name of the program at the +command line. + + +However, users should avoid starting up new programs unnecessarily - since each additional program +reduces the memory available for the programs already running. + + +To run a program synchronously, prefix the program name with an «. Note however that the command +offenable 0 should be issued before synchronously executing any lengthy program - otherwise it will be +impossible for the user to switch the HC off until the program has completed. + + +Terminating programs + + +Many programs include a facility that allows user termination. For example many programs contain an +Exit menu command. + + +When required the user can kill a program from the Command Shell, using either the terminate or kill +commands. As explained in the alphabetical listing (see below), terminate should be used in preference +to kill whenever possible. + + +A program run synchronously can not be terminated by tasking to the Command Shell that launched it - +since that Command Shell is inaccessible until the program terminates. In extreme circumstances it may +be necessary to reset the HC. + + +When a program launched from a Command Shell terminates, either normally or abnormally, the Shell +reports this fact to the user. + + +3-2 + + +3 HC COMMAND SHELL + + +The command line editor + + +Up to eight previous commands can be reviewed by means of the UP and DOWN cursor keys at the +command line. Any previous command displayed in this way can be edited before being issued again. + + +To clear the command line at any time, press ESC. + + +As might be expected, each individual command is entered to the HC by pressing ENTER after typing its +name. In most cases, the name can be abbreviated, as indicated in the alphabetical listing below. + + +Pausing the screen display + + +Some commands (such as iproc and iseg) automatically pause when a screenful of information has been +displayed. Other commands (such as dir) must be entered with a /p flag to obtain the same effect. In +either case, pressing any key will resume the display (though the ESC key sometimes terminates the +command listing). + + +At all times, the display of the Command Shell can be paused, independently, by means of the PSION+LEFT +key combination (or by SHIFT+LEFT on restricted keyboards (this feature is shared by all console +programs). Again pressing any key will resume the display. + + +Additional copies of the Command Shell + + +The Command Shell can be run from the command line just like any other program. The first and +subsequent copies of the Command Shell differ only in that, by default, subsequent copies terminate as +soon as they have processed the command lines passed to them. + + +For example typing sys$sh1l ver runs a copy of the Command Shell with the command line argument +ver. The effect is the same as simply typing ver on its own except that the new copy of the Shell +terminates after the ver command completes. The display then reverts to that of the previous Command +Shell. + + +To force a copy of the Command Shell to pause before terminating, type /p immediately after sys$sh11. +Thus + + +sys$shll /p ver +causes the display to pause waiting for any keypress, after completing listing the version information. + + +Exceptionally, if there is little available memory on the HC (for example, if there are many files on m:) +additional copies of the Command Shell may fail to perform fully as expected. + + +Sending commands from a remote PC + + +The utility of running second copies of the Command Shell is most apparent when used in conjunction +with MCLink. MCLink allows programs on the remote computer (in this case, the HC) to be invoked with +the MCLink run command. + + +For example, typing +run sys$shll /p del *.bak + +at the MCLink command line is essentially equivalent to typing +del *.bak + +at the command line of the HC. + + +Operators may find typing at the PC to be more convenient than typing on the naturally more restricted +keyboard of the HC. In cases where the HC has only a numeric keyboard, commands must be entered +using a mechanism such as MCLink running on some remote computer. + + +The following alias may prove especially useful: typing +| +at the MCLink command line is shorthand for typing +run sys$shll +Thus typing +! /p del *.bak +at the MCLink command line may be a yet more convenient way of issuing the HC with the command + + +del *.bak + + +3-3 + + +HC PROGRAMMING GUIDE + + +Often even typing these few characters is undesirable (it is impossible in the case of restricted keyboard +HCs) and so a batch file is used instead. A batch file autoexec.btf is placed in the root directory of an SSD. +This batch file is executed whenever the HC is reset - if the file contains the command link, the Link +software will automatically be started every time the HC is reset. Another (more advanced) possibility is to +place an alternative (custom) shell on an SSD, before resetting the HC. + + +More on running programs remotely + + +Even if an alternative (custom) shell is running on an HC, the Command Shell can in many cases still be +invoked by means of typing (eg) + + +! /p ver + + +at the command line of MCLink. This mechanism may be found useful in cases where it is briefly +required to access the functionality of the Command Shell, even though, ordinarily, a custom shell is run +in place of the Command Shell. + + +Occasionally this mechanism will fail to work - for reasons explained below - with a second copy of the +custom shell being run instead. + + +The MCLink run command proceeds as follows: + + +e first, an extension .img is added to the program name supplied and if no extension was explicitly +supplied + + +e the Link software starts looking, on the remote computer, for a program with this name; if at any +stage a program with this name is found, an attempt is made to execute it; if this attempt fails, +the search continues + + +e the first place searched is the current path of the Link software on the remote computer (see +below for an explanation of the concept of current path) + + +e the search continues, if required, in the ROM of the remote computer + + +e finally, if required, the search continues on all the root directories of the remote computer, in +alphabetical order. + + +Accordingly, if the current path of the Link software on the HC contains a custom copy of sys$shll.img, +this copy will be launched by an MCLink ! command; otherwise, it will be the Command Shell (from the +HC ROM). + + +In practice, the only way for the current path of Link software on an HC to differ from m-\ is for a set +command to be issued before the Link software is started. + + +There is one further complication when attempting to simultaneously run two different programs with the +same name. Ordinarily, Epoc will refuse to allow the second program to run and will generate a "File +already exists" error message. The only exception is if the second program is in ROM. This explains why +the Command Shell can be started when a custom shell is already running, whereas a custom shell cannot +be started with the Command Shell still running (try it and see). + + +Auto-terminating and non-auto-terminating Command Shells + + +A Command Shell will only auto-terminate if invoked with a command line. Whether an instance of the +Command Shell is the first or an additional copy is irrelevant. To run an additional copy of the Command +Shell that does not auto-terminate after processing its command line (either straightaway, or after pausing +to receive a keypress), just type sys$sh11 by itself, without any additional parameters (any "Capture failed +- File already exists" error message can in this case be safely ignored). + + +Files and directories + + +File In Use error messages + + +On the HC an open file can only be accessed by the application that opened it. An attempt by another +application to modify the file will lead to a File In Use error message. + + +As a consequence file commands issued from the Command Shell will fail when asked to access an +already open file. For example an attempt to copy an open file will generate a File In Use message. + + +3-4 + + +3 HC COMMAND SHELL + + +Default path and current directory + + +In Epoc there is one current path for each running process (in Epoc it is preferable to refer to the current +path rather than the current directory as this also includes the drive and the filing system). In contrast +MS-DOS logs a current directory for each drive and thus has as many current directories as drivers. + + +The current path of a Command Shell can be altered using the cd command. For example cd b:\play +would change the current path to »:\piay. Note that this could have a quite different effect in MS-DOS. +In MS-DOS change the current directory to a:\work\ then type cd b:\play\ followed by a dir command. +The dir command will list the files in a:\work\ and not those in b.\play\. + + +Changing the current path for one application does not alter the current path for any other application. +This is in contrast to and an improvement on MS-DOS. In this case the currently logged directories in the +command shell can be annoyingly altered by running (synchronously!) another process. By the time the +second process has terminated the MS-DOS command shell may have been logged to a different drive and +a different directory. + + +The HC Command Shell also supports the command set to alter the so-called default path which affects +all applications subsequently launched. The set command has no effect on the current path of the present +application but provides the initial current path for all future launched applications (regardless of where +these applications are launched from). Thus the sequence of commands + + +cd m: +set b: +sysS$shll +dir + +cd a: +dir + +exit + +dir + + +will bring about the following sequence of directory listings: + + +e first the second copy of the Command Shell lists the contents of b:\ since its current path was set +(on initialisation) to b; with the set command.(in the parent Command Shell) + + +e next, after changing the current path of the second Shell to a.\, the second dir command lists the +contents of a:\ + + +e finally, once the second copy of the Shell has been exited, the last dir command lists the contents +of m.\ - since the current path of the parent Shell has been affected by neither the set command +(as that does not alter the current path) nor the cd command (as that altered the current path of a +different process). + + +Note that any changes to the path of a Command Shell inside a batch file will continue to have effect after +the termination of the batch file, since no new process is run up, just by virtue of a batch file being +executed. + + +Specifying file names as command parameters + + +It is not always necessary to supply the full specification for a filename when passing it as an argument to +a Shell command. The missing parts (if any) are filled in from the current path. + + +Thus if the current path is m:\img\, the command att job.img -r operates on the file with full path name +m:\img\job.img and the command att b:\backup\job. img operates, naturally enough, on the file +b:\backup\job.img - regardless of whether the current path is on m-, b:, or whatever. + + +Beware that att b:job.img is equivalent to att b:\img\job.img and not att b:\job.img (the first and +last forms differ only in the presence or not of a back-slash immediately after the colon). The reason why +these two forms are interpreted differently is that the filename b-job.img is interpreted as having three +parts: + + +e =adrive (b:) +e a basic name (job) + + +e an extension (.img). + + +3-5 + + +HC PROGRAMMING GUIDE + + +As the path is not explicitly specified, the path specified in the current path of the application will be +assumed. If the (incorrectly specified) file is not found the command will fail with the error message +"Directory does not exist". + + +To specify a file job.img on the root directory of b:, type b:\job. img, including the crucial \ character. +More details on filename specifications +Filenames are assumed to have five parts: +e =afiling system (eg loc:: or rem::) +e = adrive (eg b:) +e a path (eg \ or \accounts\jan\) +e a basic name (eg job) +e¢ an extension (eg .img). +The current path of an application contains the first three components. It does not contain the last two. + + +The filing system will always be assumed to be that specified in the current path unless an alternative is +explicitly supplied. + + +Note that various Shell commands may unexpectedly fail to work if the filing system specified in the +current path is set to rem::, and the remote link connection is subsequently broken. + + +Specifying paths as command parameters + + +When using a command such as cd it is often more convenient to omit one or more components of the +path as any missing components will be filled in from the current path. Thus with a current path of +m.\img\ the command ca files would be equivalent to cd m:\img\files and the command mad tools +would be equivalent to md m:\img\tools. + + +Note that it can sometimes be an error to supply a trailing back-slash. Whilst mad m:\img\tools\ is +acceptable, md tools\ is not. The reason is that the trailing back-slash indicates that a path component +follows - the ma command does not expect a path component to follow. + + +The requirements of generality + + +The user might consider the syntax of HC Command Shell commands to be more limiting than the MS- +DOS equivalent - the syntax of commands such as md and rd on the HC is not the same as that of the ma +and rd commands in MS-DOS although there are considerable similarities. + + +The extra limitations stem from a central design feature of the Epoc operating system - under Epoc an +application can directly access files that are stored on a remote computer whose filing system may or may +not be MS-DOS. Alternative remote filing systems that need to be borne in mind include Unix, Vax VMS, +and the Apple Macintosh operating system. + + +Thus if the HC is connected to an Apple Macintosh computer, the following could be entered at the +command line: + + +cd rem: :hd40:hcdevp: stock + + +Accordingly, the HC Command Shell does not simply approach filenames and path specifications in terms +of questions of back-slashes (were the Shell to insert a back-slash at the end of the above command, "on +behalf of the user", this would, most decidedly, not be what the user intended). Instead, the approach is +much more general, in terms of the five part breakdown of filename specifications discussed two sections +previously. + + +Similarly, the HC provides no support for the syntax of "double dot" (for the parent directory) and "single +dot" (for the current directory). + + +Although this extra discipline has its occasional drawbacks, the advantages that it brings with it are an +important part of the vital inter-connectable feature of the HC. + + +3 HC COMMAND SHELL + + +Alphabetical listing +Notation +This list of commands uses the following syntax: +COM[MAND] supplied-parameter [optional-parameter] + + +Items shown in square brackets ([]) are optional. To include optional information, type only the +information within the brackets. Do not type the square brackets themselves. + + +Legal shortened versions of commands may be inferred from the syntax given. Thus in the above +(generalised) example, com would be an acceptable shortened form of commanp. Any intermediate form +between com and command would also be acceptable - eg comm (but not comd, needless to say). + + +Commands can be typed in any combination of lower and upper case. For example, except where clearly +stated to the contrary below, pairs of command such as wnot on and wnot on are completely equivalent. + + +Commands must be separated from their options by inserting a space character. + + +Default values may be assumed if some options are not supplied. Default values of particular commands +are given in the individual command descriptions which follow. + + +Note: the following list actually contains two entries that are not really commands of the Shell, in the +strict sense, but are just the names of programs in the rom: 1ink and bat chk. However, this distinction +may seem irrelevant to the user, and so, for convenience, these commands are listed too. + + +How commands are implemented + + +In many cases, the description of a command below gives the name of some of the key C functions +involved in the implementation of that command. This is provided partly for interest, partly as an +additional reference source (so that the corresponding section of the Plib Reference or Window Server +Reference manuals can be consulted), and partly as a guide for people wishing to write an alternative shell +(or shell-like) program. + + +Command ATTRIBUTE _ Setor clear file attributes (ATTRIBUTE) + + +ATT[RIBUTE] filename [(+/-)h] [(+/-)s] [(+#/-)m] [(+/-)r] +Sets or resets the hidden (nh), system (s), modified (m) and/or read-only (x) attributes of a file. + + +For example, att list.dat -m +s clears the modified attribute and sets the system attribute of list.dat, +without altering its hidden or read-only attributes. + + +For each of h, s, m, and r, a prefix of - clears the corresponding attribute, and a prefix of + sets it. The four +attributes can be specified in any order, and any combination of the four bits can be set or cleared at once. +Omitting all four is pointless: nothing will happen. + + +The attribute command does not accept a wild card specification. +This command is implemented via the C function p_sfstat. + + +Note that the air command includes the attributes of files as part of its display. + + +Command AUTO Set time to auto-switch-off (AUTO) + + +AUT[O] seconds +Sets the time for auto-switch-off. + + +The auto-switch-off time is set to seconds. If seconds is -1, auto-switch-off is disabled. The maximum +value for seconds is 32767, and the minimum non-zero value is 15. + + +This command is implemented via the C function p_setauto. + + +HC PROGRAMMING GUIDE + + +Command BACKLIGHT Set backlight time-out (BACKLIGHT) + + +BACK[LIGHT] [time] + + +Sets the backlight auto-time-out to time, or if time is omitted, displays the current setting (in +hexadecimal). + + +The value of time is in ticks, ie 1/32 of a second. +If time is zero, the backlight will remain on for as long as the HC is switched on. + + +Passing time as negative has the effect of disabling the BACKLIGHT key. In that case, the backlight can +only be switched on under software control. + + +This command is implemented via the C functions p_backlight, p_getbacklight, and p_setbacklight. + + +Command BATCHK Start battery check program (BATCHK) + + +BATCHK interval +Starts the program rom::batchk (if found), which monitors the voltages of the main and backup batteries. + + +The value of interval gives the time period, in tenths of a second, between the time when checks are +made. + + +If either battery is found to be low when a check is made, a Notifier is displayed. + + +The batchk program also captures the INFO key so that, whenever this key is pressed, the user is presented +with information on the current voltages of the batteries. At the same time, a Notifier is displayed if +either battery is low. + + +Passing interval as 0 has the effect that a check on the battery voltages is performed only when INFO is +pressed; no timer operates in this case. + + +If interval is omitted, it defaults to 3000 (5 minutes). Any value of interval less than 100 has the same +effect as passing 0. + + +A copy of batchk is automatically run when the Command Shell starts. The Command Shell starts batchk +with a value of interval equal to zero. + + +Attempting to run a second copy of batchk without terminating the first will result in an error message +and then a notification of abnormal program termination (the second copy of batchk). In order to change +the value of interval that is in operation, to ten minutes (say), the following has to be entered: + + +term batchk +batchk 6000 + + +See the lowbat command for an independent method of checking the battery voltages. + + +The core functionality of the batchk program is provided by the C calls p_supply and p_wsupply. +Applications in which it is critical that battery power does not drop too low during some activity should +make their own calls to these functions when needed. + + +Command BATTERY Specify battery type (BATTERY) + + +BAT[TERY] type + + +Specifies which type of main battery is installed. This information may be used by other software on the +HC, affecting (eg) when low battery warnings are issued. + + +Allowed values of type include: + + +1 alkaline batteries + +2 600 mAh Nickel Cadmium batteries +3 1000 mAh Nickel Cadmium batteries +4 500 mAh Nickel Cadmium batteries. + + +This command is implemented via the C function p_setbat. + + +3-8 + + +3 HC COMMAND SHELL + + +Command CD Change directory (CD) +CD [path] +Changes to a different path, or (if path is omitted) displays the current path. +For example, to change the current directory from \work\product\ to \work\admin\, type +cd \work\admin\ + + +To move to a directory below the current one, only the path from the current directory needs to be entered. +So to change from \work\admin\ to \work\admin\forms\, the following command could be used: + + +cd forms\ +The trailing back-slash in the above commands can be omitted. Thus cd forms instead of cd forms\. +There is no support for a command such as ca .. (to move to the parent directory). +Type cd b: (or ca b:\) to change to the root directory of b:. + + +This command is implemented via the C function p_setpth (amongst others). + + +Command CONFIG Set language file (CONFIG) + + +CON[FIG] filename + + +Changes the language data file to that specified. If £i1ename is omitted, the effect is to revert to the file +sys$ctry.cfo. + + +If the extension is omitted, it is assumed to be .cfo. + + +The file given must be in the ROM of the HC. Unless a specially customised version of the ROM has been +made, this in practice limits the use of this command to + + +config custom$.dat +where the file custom$.dat has been specially prepared by means of the tool romwrite. + + +The effect of specifying a file that has an unsuitable form is drastic: almost certainly, the HC will require a +hard reset to recover. + + +This command is implemented via the C function p_setconfig (amongst others). + + +Command COPY Copy file(s) (COPY) + + +COP[Y] source_filespec target_filespec +Copies one or more files, possibly changing their names in the process. + + +Any part of the target filename that is not specified (for example, the extension) and which cannot be +filled in from corresponding parts in the current path is taken from the corresponding part of the first +pathname. + + +The wildcards « and ? can be used to copy multiple files. + + +For example, copy fred.* a:\jim.* copies all files such as fred.btf from the current directory into the +root of a.\, renaming them (eg to jim.btf) in the process. + + +As a possibly surprising example, if the current path is m-:\, the command copy a:\file.lis file.old +has the effect of copying the named file to m.\file.old. + + +As files are copied, the names of the files created are listed on the screen. + + +A file cannot be copied onto itself. If an attempt is made to do this, the copy command quits, and an error +message such as the following is displayed: + + +Copy failed - file or device in use + + +This command is implemented via object-oriented techniques using the fman object in Olib.dyl. + + +3-9 + + +HC PROGRAMMING GUIDE + + +Command D Brief directory listing (D) + + +D [/p] [filespec] + + +Lists specified filenames in a directory, without any additional information except for the total size and +the total number of bytes free on the current device. + + +Typing d by itself lists all filenames in the current drive and directory. Typing a and a path, such as a:\, +lists all entries in the specified directory. If a filename without an extension is included (invoices, for +example), all files named invoices in the specified directory will be listed, whatever their extension. + + +The wildcards « and ? can be used in the file specification. + + +The /p flag causes the display to pause at the end of each screen. When the display is paused, it can be +resumed by pressing any key. However, if ESC is pressed, the directory listing is terminated. + + +This command is implemented via the C functions p_open(P_FDIR), p_dinfo, and p_iow(P_FREAD). + + +Use the dir command for a fuller listing of the details of files. + + +Command DATE Display date and time (DATE) + + +DAT[E] +Displays the current date and time. +This command is implemented via the C function p_date. + + +Use the setdat command to change the date and/or time. + + +Command DELETE Delete file(s) (DELETE) + + +DEL[ETE] filespec +Deletes the specified file or files. + + +To delete more than one file at a time, the wildcards * and/or ? can be used. Alternatively, the following +deletes all files in the directory \temp\: + + +del \temp\ +As files are deleted, the names of the files deleted are listed on the screen. + + +This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which +result, in the end, in calls to the C function p_delete. + + +See also the command ra, which, in contrast to del, can delete directories. + + +Command DEVICE List devices (DEVICE) + + +DEV[ICE] [filespec] + + +Lists all devices ("drives") in the filing system specified by f£ilespec. The only relevant part of filespec +is the filing system (loc::, rem::, or whatever). + + +For example, dev rem:: lists the devices in rem:: - assuming a remote connection is established. +Typically, the command dev just results in the following listing: + + +List of file devices for LOC:: + + +A: - OK +B: -— OK +M: - OK + + +In practice, the only time a device will be reported as other than "ox" will be if the connection to a remote +computer is broken midway through listing the devices of rem::. + + +This command is implemented via the C functions p_open (P_FDEVICE) and p_iow(P_FREAD). + + +3 HC COMMAND SHELL + + +Command DIR Full directory listing (DIR) + + +DIR [/p] [filespec] + + +Lists all the specified files in a directory, together with their sizes, the time and date of their last +modification, and their attributes. + + +The wildcards * and ? can be used in the file specification. + + +The /p flag causes the display to pause at the end of each screen. When the display is paused, it can be +resumed by pressing any key. However, if ESC is pressed, the directory listing is terminated. + + +This command is implemented via the C functions p_open(P_FDIR), p_dinfo, p_iow(P_FREAD), and +p_finfo. + + +Use the a command for a briefer listing of the details of files. + + +Command ENV Display or set environment variable (ENV) +ENV [var[=[value] ]] +Displays or sets the value of environment variables. + + +With no parameters, the values of all current environment variables are displayed. If var is given but +without any trailing equals sign (=), the values of all environment variables matching the specification in +var are listed. If the equals sign (=) is given too, the environment variable var is set to value. But if the +equals sign is given whilst value is omitted, the environment variable var is deleted. + + +For example: + + +env $wWs* displays the values of all environment variables whose names start with sws +env last=34 sets the value of 1ast to the string 34 +env last= deletes the environment variable 1ast. + + +Values are displayed inside square brackets. The list pauses when the screen is full. + + +Note that environment names and values are both case dependent. Thus the environment variables group +and croup would be distinct. + + +Indeed, environment names and (more likely) environment values can even be binary. Non-printable byte +values are displayed as (eg) or . There is no mechanism for setting binary values from the +Command Shell. + + +This command is implemented via the C functions p_findenviron, p_delenv, and p_setenv. + + +Command EXIT Exit level (EXIT) + + +EXI[T] + + +Exits the Command Shell. May be used to terminate second copies of the Command Shell that are no +longer required. + + +If the exit command is typed into the first copy of the Command Shell, the HC will automatically re- +launch a shell process, as explained in the chapter Introduction to the HC. + + +If the exit command is found in a batch file, all that happens is that the batch file is terminated, and +control passes back to the previous level of batch file (or to the command line). + + +The command is implemented (when not in a batch file) by the C function p_exit. + + +Command FORMAT Format device (FORMAT) + + +FOR[MAT] [device:] [volname] + + +Formats Ram and Flash SSDs (or the internal disc m:). + + +HC PROGRAMMING GUIDE + + +The command detects the type of SSD and places the appropriate format information onto the disk. This +information differs for Flash and Ram SSDs. + + +The volume name volname is optional. +For example, format a:new will format the a: device, giving the volume name new. +If device: is omitted, the internal memory is formatted. + + +Note carefully that no warning is given before the formatting takes place. So accidentally typing (eg) for +b could be disastrous: + + +e since no colon is typed, b is interpreted as the volume name +e since no device name is specified, formatting defaults to m: +e accordingly, all data on m: is lost in a trice (with the volume name of m: being set to b). + + +The mere fact that there are read-only files on an SSD will not prevent it from being formatted. However, +if an SSD has the write-protection switch set, it will not be possible to format it. + + +Another reason for format being disallowed for a disk would be if there are any open files on it. In this +case, the format request will fail with the error message "File or device in use". + + +This command is implemented via the C functions p_open (P_FFORMAT) and p_read. + + +Command FREE Display free memory (FREE) +FRE [E] +Displays the amount of free RAM in Kbytes. + + +Note that this in general exceeds the amount of bytes free in m:, as reported by a dir or d command. The +discrepancy is because some parts of internal memory are reserved for code and data segments; not all of +it can be allocated to the contents of m:. + + +This command is implemented via the C function p_sgfree. + + +Command KILL Kill a process (KILL) + + +KIL[L] procname +Kills the first process found matching the specification in procname. + + +To kill a specified instance of a number of running tasks, all with the same name, the exact process name +must be found out and used. Eg kill job.$09 Or kill job.$14. + + +Use the 1proc command to give the full process names of all current processes. + + +Note that ki11 should only be used as a last resort, as it does not allow the process to tidy up before +exiting - this is a problem with the Link application which starts a number of sub-processes. To shut down +a process, terminate should normally be used in preference to kill. + + +This command is implemented via the C function p_pkill. + + +Command LDEV List device drivers (LDEV) + + +LDE[V] [device_spec] + + +Lists all specified device drivers. The list includes all ROM-resident device drivers, as well as external +ones that are currently loaded. + + +If device_spec is omitted, it defaults to *.*. + + +For each device driver listed, the label /dd or pdd is given - the former for logical device drivers (which +are hardware-independent), the latter for physical device drivers (which are hardware dependent). + + +3-12 + + +3 HC COMMAND SHELL + + +For example, entering 1dev con displays + + +List of devices:con + + +LDD - CON (units=-1) + + +The value given for units is the number of channels a logical device driver can support. A value of -1 +means that an unlimited number of channels can be opened. + + +As another example, entering 1dev fsy displays +List of devices:fsy + + +PDD - FSY.REM +PDD — FSY.LOC +PDD - FSY.ROM + +listing the three ROM-resident filing system device (fsy) drivers - for rem::, loc::, and rom::. + + +This command is implemented via the C functions p_devfnd and p_devqu. + + +Command LINK Start Link program (LINK) + + +LINK [-b] [-p] [filename] +Starts the Link communication software on the HC. + + +If filename is specified, it is assumed to specify a .trm file, and in that case, there should be no other +parameters on the command line. The extension .trm is supplied for filename if required. + + +If the command line is empty, the Link software searches as follows for a file mclink.trm to configure it: +e first, in the current path of the Link software +e next, in the HC ROM (where it will indeed find a file mclink.trm). + +The format and creation of .trm files is discussed in the Additional System Information manual. + + +Possible values of baud range from 19200 and 9600 all the way down to 110, 75, and 50, with all common +baud rates in between being supported. In the absence of a command line and if no external mclink.trm +file is found, baud defaults to 9600. If the port or serial_device 1s specified but not baud, baud defaults +to 19200. + + +The only time it is necessary to specify port is if there are serial expansion devices in both the top and the +bottom of the HC. In this case, the parameter -p1 means to use the top port, and -p2 means to use the +bottom port. Otherwise, the Link software simply uses whichever port is available. + + +(Other parameters are also possible but are omitted from the present description. See the chapter Mclink, +Mcprint, and Slink in the Additional System Information manual.) + + +Just typing 1ink should suffice in the majority of cases. +To terminate the Link software at some later date, type term link. +To discover whether or not Link software is running, type lproc link. + + +If the 1ink command is issued while Link is already running, a second copy of Link will be launched +briefly, but will quickly exit with the error number -32 (or 224), meaning that a process link. * already +exists. No harm will ensue as a result. + + +See the section Connecting to other computers in Introduction to the HC, for more details. + + +Command LOWBAT Configure low battery warnings (LOWBAT) + + +LOW[BAT] state + + +If state is on, the HC will check, each time the HC is switched on, for either of the batteries being low. +On detecting a low battery, the HC will issue a warning in the form of an information message in the +bottom right hand corner of the screen. + + +3-13 + + +HC PROGRAMMING GUIDE + + +If state is orr, this behaviour will not take place. (This is the default.) +This command is implemented via the C function wsystem. + + +See also bat chk for an independent method of periodically checking the battery voltages. + + +Command LPROC List processes (LPROC) + + +LPR[OC] [process_spec] +Lists information about all specified processes. The information listed is: +e the full process name (in the form batchk.$07) +e the size, in bytes, of the process data segment (given in hexadecimal) +e the current state of the process. +If process_spec is omitted, it defaults to *.*. +Possible values of the state of the process are: +CURRENT the process is currently receiving cpu + + +READY the process has some events ready to process, as soon as cpu is given to the +process by the multi-tasking scheduler + + +DELTA the process is "sleeping" (eg as a result of calling the C function p_sleep) +sus the process has been suspended +SEM the process is waiting for some event to happen. + + +Additionally, the text wsusp will be displayed if the process is waiting to be suspended. +For example, entering lproc sys$shll may produce the display +List of processes:sys$shll + + +SYSSSHLL.$05 3DA0 SEM +SYSSSHLL.$11 3DA0 CURRENT + + +One common use of the lproc command is to check whether Link software is currently running: 1proc +link. + + +This command is implemented via the C functions p_pfind, p_getosd, and p_sgsize. + + +Command LSEG List segments (LSEG) + + +LSE[G] [process_spec] +Lists all memory segments currently in use by the specified process(es). +If process_spec is omitted, it defaults to *.*. +The information listed about each memory segment is: +e its size in paragraphs (one paragraph is sixteen bytes) +¢ its segment address +e its access count. +Values are displayed in hexadecimal. + + +At the end the display, the total size in paragraphs of all the free segments is given (this gives the same +value, when converted into Kbytes, as free). + + +This command is implemented via the C functions p_sgfind, p_getosd, and p_sgfree. + + +3-14 + + +3 HC COMMAND SHELL + + +CommandMASTER Display time/date of mastering (MASTER) + + +MAS [TER] +Displays the time and date when the ROM was mastered. + + +The command is implemented by the C function p_finfo, passing as a parameter a file known to be in the +ROM (rom: :sys$shll.img). + + +Command MD Make directory (MD) + + +MD path +Makes a directory. + + +When a directory is created, it will appear in the current directory, unless a different path is explicitly +specified. + + +It is possible to omit the trailing back-slash from the path specification. +The following commands both create a directory named \work\ in the root directory of the current drive: + + +md \work\ +md \work + + +This command is implemented via the C function p_mkdir. + + +Command NOTIFY Control whether the Notifier appears (NOTIFY) + + +NOT[IFY] state + + +Controls whether the Notifier ever appears as a result of a file operation carried out by the Command +Shell. + + +If state is on (this is the default), and a file operation unexpectedly fails to find an SSD that was present +earlier, a Notifier will be presented giving the user the opportunity to replace the SSD, instead of just +having the file operation fail. + + +If state is orF, no such Notifier will be displayed. + + +The notify command in the Shell has no effect on whether Notifiers are ever displayed by other +programs. + + +This command is implemented via the C functions p_setnotify and p_getnotify. + + +Command OFFENABLE _ Enable off-key handling (OFFENABLE) + + +OFFE[NABLE] value + + +If value is 0, the Command Shell gives up its capture of the OFF key, thereby allowing other applications +to capture this key to do their own processing of it. + + +If value is any non-zero number, the Command Shell attempts to capture the OFF key again. +This command is implemented via the C functions wcaptureKey and wcancelCapturekey. + + +Note that there is no special need to have any application capture this key, since by default, the HC simply +switches itself off when this keypress is received. The behaviour of the Command Shell in response to the +OFF key adds nothing to this. + + +Indeed, it is recommended that the command offenable 0 be issued early in any autoexec.btf start-up +batch file. + + +Command RD Remove directory (RD) +RD path +Deletes a directory, including any files in it (and subdirectories). + + +Note that, in contrast to MS-DOS, there is no requirement to delete all the files in a directory before +removing the directory. Further, no warning is given before the directory is removed. + + +HC PROGRAMMING GUIDE + + +In another difference from MS-DOS, it is perfectly possible, in the HC Command Shell, to remove the +directory where the current path is. All that will happen is that subsequent commands such as dir may +fail until such time as the current path is changed. + + +As files and directories are deleted, their names are listed on the screen. +The rd command does not accept a wildcard specification. + + +This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which +result, in the end, in calls to the C function p_delete. + + +Command RENAME Rename file(s) (RENAME) + + +REN[AME] filespec filename +Changes the name of a file or files. +The command renames all files matching filespec - which can include wildcards. + + +For example, the command ren work.* play.* changes the names of all files called work in the current +directory (regardless of extension) to play, with the extension being preserved across the rename. + + +As files are renamed, they are listed on the screen. + + +Because it is not possible to rename files from one directory to another, the command fails if any path +specified with filename (explicitly or implicitly) differs from that of filespec. + + +It is not possible to rename a file to have the same name as a file that already exists. + + +This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which +result, in the end, in calls to the C function p_rename. + + +Command RESUME Resume a suspended process (RESUME) + + +RES [UME] procname +Resumes the previously suspended process procname. +See also suspend, + + +Some care needs to be exercised in the use of this command, to resume an instance of process job (say), in +any case where there may be more than one instance of job running at a time. This is because the +command simply attempts to resume the first instance of the process job found, regardless of whether or +not that particular process is actually suspended. + + +This command is implemented via the C function p_presume. + + +Command SET Set default path (SET) +Sets the default path. + + +For example, the command set b:\ has the effect that all subsequently launched tasks start with their +current paths set to b:\. This may be useful if a program assumes that its current path on start up is where +it should read and/or write certain files. + + +See the earlier section Files and directories for further discussion. + + +This command is implemented via the C function p_setdefaultpath. + + +Command SETDATE Set time and date (SETDATE) + + +SETD[ATE] dd/mm/yy hh:mm:ss +Sets the date and time. + + +For example, setdate 26/02/92 15:10:00 sets the date to the 26th of February, 1992, and the time to ten +minutes past three in the afternoon. + + +3-16 + + +3 HC COMMAND SHELL + + +All parameter fields must be present, with a two digits being supplied for each field. +The time should always be specified in 24 hour format. + + +If yy is in the range 70 to 99, the century is set to 19. Otherwise it is set to 20. That is, the range of years +that can be set is from 1970 to 2069. + + +This command is implemented via the C function p_sdate. + + +Command SUSPEND Suspend a process (SUSPEND) + + +SUS[PEND] procname +Suspends the first process found matching the specification in procname. + + +To suspend a specified instance of a number of running tasks, all with the same name, the exact process +name must be found out and used. Eg suspend job.$09 OF suspend job.$14. If only one instance of +job.img is running, it suffices to enter suspend job. + + +Use the 1proc command to give the full process names of all current processes. Use the resume command +to reverse the effect of a suspend command. + + +This command is implemented via the C function p_psuspend. + + +CommandTERMINATE Terminate a process (TERMINATE) + + +TER[MINATE] procname +Terminates the first process found matching the specification in procname. + + +To terminate a specified instance of a number of running tasks, all with the same name, the exact process +name must be found out and used. Eg ter job.$09 Of ter job.$14. + + +For most applications, the effect of being terminated is identical to being killed: the application is +interrupted immediately, with no chance being provided for data being saved to file or to environment +variables. However, an application can make use of an operating system service (in C, p_onterminate) to +specify behaviour to be invoked whenever the application is to be terminated in this way. + + +This command is implemented via the C function p_pterminate. + + +Command TYPE Type a text file (TYPE) + + +TY[PE] filename +Prints a text file to the screen. + + +There is no provision for the display to pause itself automatically. However, the user can pause the display +at any time, in the usual way, by pressing PSION+LEFT. + + +This command is implemented via the C functions p_open (P_FTEXT) and p_read. + + +Command VER Display software version number (VERSION) +[VER] SION + + +Displays the Operating System (Epoc) version number, the HC Rom version number, and the Command +Shell version number. + + +This command is implemented via the C functions p_version and p_romversion. + + +Command WAIT Wait for a process to complete (WAIT) +WAI [T] + + +Waits until a process completes. The message "Waiting" is displayed and the Shell becomes non- +interactive until such time as another process completes. + + +To break out of this mode, press PSION+ESC. + + +HC PROGRAMMING GUIDE + + +Commonly, this command will be used inside batch files in the following general pattern: + + + + + + +wait + + +Command WNOTIFY Configure Notifier appearance (WNOTIFY) + + +WNO[TIFY] state +Configures the appearance of the Notifier. + + +If state is orr, the Notifier will be drawn in the same way as it was for software versions prior to release +1.50 of the HC ROM. (This is the default.) + + +If state is on, the Notifier will be drawn in an arguably more attractive form, and will also be displayed +automatically whenever any program terminates abnormally. This form of the Notifier also involves less +RAM usage. + + +The w in the name wnotify stands for Window Server - the part of the operating system which actually +produces the more attractive version of the Notifier display. + + +To see what a Notifier looks like under either of the two methods, first terminate Link (if it is running) +and then type (eg) + + +link x +This brings about a "File does not exist" Notifier, since the file x.trm (presumably) does not exist. +This command is implemented via the C function wsystem (amongst others). + + +Using the command fre before and after typing wnot on should reveal a memory saving of around 7 +Kbytes. + + +What happens when the Command Shell starts + + +Exactly what happens when the Command Shell starts depends on whether it has been passed a command +line. + + +When the Shell is started by the Window Server (after a reset, for example), no command line is passed. +In most other cases, however, the user would pass a command line to the Shell. + + +For example, typing +run sysSshll /p ver + + +into MCLink has the effect of running a copy of sys$shl/ on a remote HC, passing it the command line /p + + +Vers +When no command line is passed + + +The Command Shell checks to see if a process sys$ntfy is already running. If not, it launches one from the +HC ROM. (However, if the Window Server has taken over the notifier function, the independent +sys$ntfy.img process will quickly discover this fact, and terminate itself silently.) + + +Similarly, the program batchk is launched, if it is not already running. + + +Next, the Command Shell searches for a batch file autoexec.btf and executes that, if one is found. The +search is on the root directories of a:, b:, and m-, in that order. If no such batch file is found, the user is +prompted to insert an SSD containing this file, and to press ENTER to continue. However, the search can +be abandoned by pressing PSION+ESC instead. + + +3 HC COMMAND SHELL + + +Then some system information is displayed on the screen: the version numbers of the ROM-resident +software, the date and time, the size of the display screen, the battery type and internal power supply type, +the reason why the operating system was last restarted, and the size of the RAM and how much of it +remains free. + + +C functions involved in the start-up display (in addition to those mentioned in the above alphabetical +listing) include p_getlcd, p_getbat, p_getpsu, and p_getres. + + +The final thing the HC Command Shell does, before starting to process commands from the user, is to +attempt to capture the OFF key to itself. + + +3-19 + + +CHAPTER 4 + + +THE HC IN THE CRADLE + + +Introduction + + +The Psion Cradle was designed to provide: +e asecure mounting for the HC. +e hands-free operation. +e battery recharge. +e high speed data transfer with a PC. + + +The cradle automatically engages with the high speed serial port on the HC and can be connected via a +high speed cable to a PC. Running special software on the PC enables a high speed serial connection that +is significantly faster than the standard serial connections described elsewhere. + + +See the chapter Introduction to the HC for additional background details about the Cradle. +Port C + + +The Cradle contains an expansion socket that can accept some, but not all, of the HC's standard expansion +modules. This expansion socket has name "Port C" as seen by software (the two standard HC ports have +names "Port A" and "Port B". + + +For example, software that opens Try:c will open any serial port in the Cradle expansion slot. + + +Link software can use a standard serial port fitted into the Cradle. The Link software must be invoked as +follows: + + +link -p3 -b9600 +This allows the Link software to operate at standard rates of data transfer, i.e. up to Baud 9600. + + +The remainder of this chapter describes various kind of higher speed connections that are possible +between a PC and an HC. These require the expansion port of the Cradle to be fitted with a special high +speed serial module. Note that this module will not operate if it is connected into either Port A or Port B +of an HC - it has to be fitted into Port C. + + +Hardware connections +The high speed cable plugs into a special socket on an ASIC-2 expansion card fitted in the PC. + + +The remainder of this chapter assumes that the PC has an ASIC-2 expansion card fitted, and that the high +speed cable connects into this card. + + +Fitting an ASIC-2 expansion card + + +An ASIC-2 expansion card in a PC contains two sockets: +e the upper one is designed to be connected to a (local) set of SSD drives + + +e the lower one is designed to be connected to a high speed cable leading to an HC Cradle. + + +HC PROGRAMMING GUIDE + + +The two possible uses of an ASIC-2 card in a PC are completely independent from each other. Any local +SSD drive can be accessed as long as software device drivers such as devram.sys have been loaded by the +config.sys program on the PC (the drivers ifs.sys, fefs.sys, and devflash.sys also need to be loaded to +access Flash SSDs in these drives), none of these drivers are required for the high speed socket to work. + + +The ASIC-2 card occupies eight consecutive memory addresses, and uses one hardware interrupt. A set of +jumpers on the card controls these two settings. + + +The standard ASIC-2 card works with MS-DOS versions 3.2 upwards. It is suitable for all PCs, XTS, +ATs, and fully compatible computers. A variant of the card is also available for MCA-based computers, +such as most PS/2 models. + + +Full details of installing and configuring the ASIC-2 card are contained in the documents Installing the +Psion SSD/ fast serial card for PCs and Installing and using the Psion SSD software and SSD drive unit +for PCs that accompany the ASIC-2 expansion card. + + +Software connections + + +There are two quite separate software mechanisms for connecting an HC in a Cradle to a PC with an +ASIC-2 expansion card: + + +¢ running suitable Link software on each end of the connection, allowing high speed remote file +access between the two computers + + +e using the pmx: device driver on the HC and the hssram.sys device driver on the PC, allowing +RAM SSDs in the HC to be accessed from the PC as if they were SSD drives directly connected +to the PC. + + +At the time of writing, the remote file access supported by the ASIC-2 card allows data transfer on +average about four times faster than that possible using a standard RS232 serial connection between an +HC and a PC. The PMX/HSS mechanism allows data transfer that is considerably faster than this. +However: + + +e the PMX/HSS mechanism only allows access to RAM SSDs in the HC, not (at the time of +writing) to Flash SSDs, nor to the "internal" drive (m-) + + +e the PMX/HSS mechanism only allows access to the HC SSD drives from the PC: there is no +question of access to the PC drives from the HC. + + +Evidently, the two different mechanisms are both well-suited to different circumstances. +Check with Psion on the availability of a driver hssflash.sys allowing access to Flash SSDs in the HC. +High speed remote file access using Link software +In order for Link software on the HC and on the PC to use the high speed connection, the parameter +-stty:z +needs to be specified. +Thus at the HC end: +e any current Link software should be terminated, using the command term link. +e Link software should then be started (or restarted), using the command link -stty:z. +At the PC end, the same parameter should be passed on the command line to MCLink. +To check that a connection has successfully been established, simply type dir rem:: at either end. + + +In both cases, other parameters on the command line (such as an explicit value for the Baud rate) will +generally be ignored. + + +As is standard for Link and MCLink software, command line parameters can be specified implicitly by +creating .tvm files. For example, any parameters in a local file mclink.trm (as created by a set command +inside MCLink) will apply, in the absence of any other contents on the command line. For more details, +see the chapter Mclink, Mcprint, and Slink in the Additional System Information manual. + + +Version 3.0 or higher of MCLink is required, in order for the -stty:z parameter to be recognised. + + +4-2 + + +4 THE HC IN THE CRADLE + + +High speed debugging using Link software + + +The Sibo Debugger can use a high speed connection to cut down on the time spent in data communication +between the PC (where the Debugger runs) and the HC (where the program being debugged runs). + + +For general information about the Sibo Debugger, see the Sibo Debugger manual. + + +As always when using the Sibo Debugger, Link software has to be running on the HC. In order for the +Link software to use the high speed connection, the parameter -stty:z has to be specified: + + +link -stty:2 +The same parameter has to specified on the command line of the Debugger. Thus instead of typing e.g. +\sibossdk\sys\sdbg sample + + +to debug the program sample.img, the following should be typed: + + +\sibosdk\sys\sdbg -stty:z sample + + +The PMX/HSS mechanism + + +If the following line (or equivalent) is placed in the config.sys start-up program for a PC +device=c:\ssd\hhsram.sys +and the PC has an ASIC-2 expansion card fitted, the PC will gain four more disc drives. + + +If the PC ordinarily has floppy drives a: and b-, and a hard disk c:, then drives d: through g: will be +added by this process. + + +However, typing e.g. dir da: at the MS-DOS command line would almost certainly lead to a message +such as + + +Not ready reading drive D: +Abort, Retry, Fail + + +This is because pmx: software has not yet been enabled at the HC end of the connection. + + +Incidentally, two definite effects of running the hssram driver on the PC can clearly be seen, even in the +absence of co-operating pmx: software on the HC: + + +e typing dir d: gives an error message of the above sort, whereas typing e.g. dir h: leads to the +more cursory message Invalid drive specification + + +e if there is a hardware connection between the PC and the Cradle, and if there is an HC in the +Cradle, the green "Data" light will flash when the dir d: command is given. + + +Configuring hssram.sys + + +The document Installing and using the Psion SSD software and SSD drive unit for PCs that accompanies +the ASIC-2 card for PCs describes how the base address of the ASIC-2 card can be altered, by means of +adjusting jumpers on the card. + + +This adjustment may occasionally be necessary, away from the default base address of 0x2a0 and +hardware interrupt 7, in order to avoid conflicts with other expansion cards already fitted in the PC (for +example, network cards or internal modems). + + +In this case, as well as adjusting the jumpers on the ASIC-2 card, you will need to change the +configuration of some of the associated software drivers. + + +When using an SSD drive unit with the ASIC-2 card, the software driver devram.sys needs to be +reconfigured (if the jumpers are adjusted). This is fully described in the document Jnstalling and using the +Psion SSD software and SSD drive unit for PCs. + + +When using the high speed connection to a HC in a Cradle, it is the software driver hssram.sys that needs +to be reconfigured (if the jumpers are adjusted). The new configuration is established in exactly the same +way as for devram.sys, except that every reference to devram.sys has to be replaced by one to hssram.sys. + + +HC PROGRAMMING GUIDE + + +For example, to change the base address to 0x370 type the following: + + +ok +cd \ssd +config -a0x370 hssram.sys + + +In practice the default settings of the jumpers and of the ASIC-2 card should be suitable for the vast +majority of PCs. + + +In case it is known to what base address the card should be set, but it is unclear how the jumpers should be +set to effect this, simply run the config program specifying the required base address (and/or hardware +interrupt number). The output of the config program specifies which of the nine jumpers on the card +should be set. + + +The PMx: device driver + + +The following very simple program demonstrates the operation of the PMX: device driver: + + +#include +#include +#include + + +LOCAL_C VOID GetKey (TEXT *mess) +{ +p_printf("Press a key to %s PMX:",mess); +p_printf("(PSION-ESC to terminate)"); +p_getch (); +} + + +GLDEF_C VOID main(VOID) + + +{ +VOID *handle; + + +FOREVER +{ +GetKey ("open") ; +p_open(&handle, "PMX:",-1); +GetKey ("close"); +p_close (handle) ; +} + +} + + +Basically, so long as the pmx: device is open by an application on the HC, any RAM SSDs in the HC will +be inaccessible to the HC filing system. Attempting to read from these SSDs will give a "Not ready" error. +Instead, these drives are given over to the control of any high speed serial requests from the PC. + + +Thus whilst the pux: device is open, typing e.g. dix d: at the PC end of the connection will give a +directory listing of the contents of any Ram SSD in drive a: of the HC. Likewise, typing dir e: at the PC +will list the contents of any Ram SSD in drive b: of the HC (this assumes that hssram.sys has been +installed on the PC and that there is only one hard disk partition on the PC). + + +When the pmx: device is closed again, the Ram SSDs in the HC come back under the aegis of the HC, and +the familiar "Not ready” message will be given in response to an attempt to access these drives directly +from the PC. + + +More details about PMX + + +The pmx: device driver has no interface other than the p_open and p_close functions used in the above +code fragment. + + +It is possible for the p_open to fail, with the following errors: +E_FILE_ALLOC failed to allocate memory for the control block + + +E_GEN_INUSE the px: driver is already open (e.g. in another application), or the high speed +port is already in use (e.g. by high speed Link) + + +E_FILE_LOCKED same as the previous case. + + +4-4 + + +4 THE HC IN THE CRADLE + + +The CRD device driver + + +The cro: device driver, which is built into the ROM of the HC, can be used to report changes of state +when an HC is inserted or removed from a Cradle. + + +The purpose of the cro: device is to allow a program to perform specific operations automatically when +the HC is inserted into a Cradle, and to "tidy up" when the HC is removed. + + +Note that the crp: device does not have to be open for the Cradle expansion port to be used in any way. +The operating system will automatically stop and start active devices in the Cradle, regardless of whether +CRD: is open. + + +See the HC Cradle and Holster chapter of the I/O Devices Reference for more details of using the cro: +device in HC programs. + + +In fact, the crp: device has a particularly simple interface (though not quite as simple as that of pmx:, +described earlier in this chapter). The entirety of the functionality of crp: when used with a Cradle is +demonstrated by the following example program: + + +include +include +include + + +LOCAL_D WORD CradleStatus; +LOCAL_D WORD CradleStat; +LOCAL_D VOID *Cradle; + + +LOCAL_C VOID ReadCrdStatus (VOID) + + +p_ioc4 (Cradle, P_FREAD, &CradleStat, &CradleStatus) ; +} + + +GLDEF_C VOID main(VOID) + +{ + +if (p_open(&Cradle, "CRD:",-1) ) +{ +p_puts ("Can't open CRD:"); +p_getch (); +p_exit (0); +} + +ReadCrdStatus (); + +FOREVER +{ +p_iowait (); +p_puts (CradleStatus? "IN Cradle": "OUT of Cradle"); +ReadCrdStatus(); +} + +} + + +In practice, of course, there would be more than one event source in the application (the only events in the +above example application are when the HC is inserted or removed from the Cradle). + + +4-5 + + +CHAPTER 5 + + +CUSTOMISING THE HC ROM + + +Introduction + + +HCs are shipped with a standard set of software programs in their rom. Application programs usually +reside on SSDs which the user has to insert into the HC. These application programs generally rely on the +ROM software in many ways, both direct and indirect. + + +For some purposes, however, it may be more suitable to alter the set of software programs that is on the +ROM of the HC: + + +e programs run out of ROM have less of a RAM overhead than those run from an SSD + + +e programs in the ROM are physically more secure than those on an SSD, in the sense that an SSD +can be removed by a user but the ROM cannot + + +¢ programs in the ROM may be able to take advantage of special software features inaccessible to +programs on an SSD - for example, the fact that ROM code and data segments always remain at +a fixed address + + +¢ programs in the ROM are easier to copy-protect. + + +All the different files comprising an HC ROM need to be assembled on a PC, and then combined into a +special master file, with extension .mas. This process involves the Psion proprietary tool erom.exe. + + +The next step is to copy the master file onto a specially formatted SSD. This requires the use of an SSD +drive attached either internally or externally to the PC, and the Psion proprietary tool emast.exe. The +outcome of this is a so-called master SSD. + + +Finally, the .mas file can be transferred from the SSD into the ROM of an HC, by the procedure of +reprogramming (or reproing for short). + + +Some cautionary remarks +The process of creating customised HC roms is not without its own considerable drawbacks: + + +e the sheer inconvenience of reproing every relevant HC, each time the customised ROM software +is upgraded, has to be weighed against the simpler alternative of just copying new program files +onto an external SSD + + +e reproing "in the field" is an impractical option, given that mains adaptors (which must be present +for a repro to proceed) are unlikely to be present or usable in these circumstances + + +e acustomised ROM may fail to be "future proof" in that future upgrades to the standard OS may +reduce the free space in the ROM to the extent that additional custom software no longer fits + + +e¢ again, a customised ROM may fail to be "future proof" against growth within the customised part +of the ROM - bear in mind that program systems almost inevitably develop over time and grow in +size as they develop + + +e acustomer who damages an HC will find it is less convenient to have it replaced or repaired if it +has been specially customised, than if it is a standard stock item + + +HC PROGRAMMING GUIDE + + +e if an unsuitable combination of files is combined into a.mas file, the outcome of reproing this +onto an HC may be a totally useless HC, that has to be returned to Psion and taken apart before +being capable of being used again (and note that HCs returned to Psion on account of a repro +failure in these circumstances would count as having violated the standard warranty conditions). + + +Incidentally, in the last of these above cases, it may be possible to rectify the situation by means of putting +another Window Server onto an SSD and rebooting the HC. This is because any program sys$wsrv.img +that is found on the root directory of an SSD is started in preference to that in the rom. At a simpler level, +putting an alternative shell (sys$shll.img) on an SSD and rebooting may also salvage matters. + + +Perhaps the largest drawback of all has not been mentioned so far. This is the possible effort required to +produce software sufficiently small that it fits on the available space remaining in the HC rom. In practical +terms, this may mean "optimising" and compressing code to the extent that it becomes unmaintainable or +otherwise flawed. However, it may still be worthwhile putting part of a customised software system into +the ROM of an HC, instead of all of it, so that at least some of the benefits mentioned earlier can be +gained. + + +Creating an HC master file + + +Invoking erom + + +The program erom.exe is used to create the master file image of the HC rom. As so many parameters must +be passed it is usually invoked via a short batch file. The following batch file mrchv.bat could be used: + + +erom >sch.mep -c -m —b0xa000 -v0x033e -lsch -oENG epocchp +type sch.mep + + +This batch file records its screen output to the file sch.mep, before printing the contents of this file onto +the screen. + + +The meanings of the other parts of this batch file are as follows: + + +-c the ROM is to be marked as suitable for reproing onto HC computers (as opposed +to others in the Sibo range). + + +-m the ROM image should be written to a .mas file. + +-b0xa000 the ROM is to have base address 0xa000 in the address map. + +-v0x033e the version number of the ROM is to be 0. 33e. + +-lsch the files listed in the text file sch.rom are to be assembled into the rom. + +-oENG the notional language of the ROM is English. + +epocchp the ROM is to be based around the version of Epoc that is in the file epocchp.exe. + + +The master file produced by this batch file, if successful, would have name v033eeng.mas. This name is +made up as follows: + + +e the first letter is always v. +e the next four letters are the version number (in this case 033e). +e the final three letters are the notional language identifier. + + +Allowed values of language identifier include: + + +ENG "English" +FRN "French" +GRM "German" +SPA "Spanish" +ITA "Ttalian" +SWE "Swedish" +DAN "Danish" +DUT "Dutch" + + +5-2 + + +5 CUSTOMISING THE HC ROM + + +In fact, erom.exe will fail if an unrecognised language identifier is specified. Note that the language +thereby identified has a purely notional role, being announced only during the process of reproing, when +the user is given a last chance to cancel before the ROM contents are changed (the actual value of +language, as determined by software calling p_get language, is set by the contents of one of the files in the +rom). + + +Valid version numbers + + +See the documentation of p_version and p_romversion in the Plib Reference manual for some +background details on valid version numbers. + + +Note that whereas roms produced by Psion are generally released with a version number ending in f, those +produced by erom.exe are automatically constrained to a final letter in the range a to e. This is to help +guard against any confusion between customised roms and those produced by Psion. + + +One other feature of the roms produced by erom.exe is that they always contain a zero-length file with the +name non$std.rom (in addition to the files specified in the sch.rom file). + + +The files comprising the rom + + +In order to produce a standard HC rom, the contents of the list file sch.rom referred to by the batch file +mrchy.bat would have to be as follows: + + +cheng.cfo,sysS$ctry.cfo +wsrvhchl.img, sys$wsrv.img +corpshll.img, sys$shll.img +corpntfy.img, sysS$ntfy.img +sysSenv.ini + +sysS$rfsv.img + +sysSncp.img + +link.img + +mclinkpa.trm, mclink.trm +olib.dyl + +big.fon + +small.fon + +mon_5x8.fon + +mono.fon + +sysSnorm.fon + +sysSbold.fon + +exopl.img +oplch.dyl,opl.dyl +batchk.img + +ttest.img + +pprint.img + +custom$.dat + + +The form of any line in this file is as follows: + + +[, ] + + +These files have the following functions (see elsewhere in the HC Programming Guide for more details): + + +cheng.cfo The standard English language "config file" for the HC (non-backlit variant) +wsrvhchl. img The Window Server program for the HC + +corpshll.img The Command Shell + +corpnt fy.img The original (non-Window Server) Notifier program for the HC +sys$env.ini Initialisation data for the Window Server + +sys$rfsv.img The Remote File Server program + +sys$ncp.img The Networking Control Protocol program used by Remote Link + +link. img The Link program + +mclinkpa.trm Standard customisation data for Remote Link on the HC + +olib.dyl A dynamic library of object-oriented classes and methods + + +HC PROGRAMMING GUIDE + + +*. fon Six different font files + +exopl.img A program facilitating the execution of Op! programs + +oplch.dyl The Opl dyl for the HC (implementing Opl/g) + +batchk. img Displays and monitors information about battery voltage levels + +ttest.img A utility program to test the status of the serial port + +pprint.img A utility program to print a specified file via a nominated peripheral +custom$.dat An initially blank file that can be written to after reproing has finished, to allow + + +additional once-only customisation. + + +Of these files, the only one that it is absolutely mandatory for the ROM to contain is a version of the +config file, sys$ctry.cfo. All others can in principle be dispensed with, though some can be replaced more +easily than others - as is discussed below. + + +Size considerations + + +The following extract from a standard .mep file (the "list" output of running erom.exe) may give some +idea as to the current amount of free space in the HC rom: + + +CHENG. CFO - B=B832 L=010FD (Hex) , 004349 (Dec) +WSRVHCH1.IMG — B=B942 L=085C0 (Hex) , 034240 (Dec) +CORPSHLL. IMG - B=C19E L=03D30 (Hex) , 015664 (Dec) +CORPNTFY.IMG - B=C571 L=007A0 (Hex) , 001952 (Dec) +SYSSENV.INI - B=C5EB L=00060 (Hex) , 000096 (Dec) +SYSSRFSV.IMG - B=C5F1 L=004F0 (Hex), 001264 (Dec) +SYSSNCP.IMG - B=C640 L=02330 (Hex) , 009008 (Dec) +LINK. IMG - B=C873 L=O00ADO (Hex) , 002768 (Dec) +MCLINKPA.TRM - B=C920 L=000E2 (Hex) , 000226 (Dec) +OLIB.DYL —- B=C92F L=04828 (Hex) , 018472 (Dec) +BIG.FON - B=CDB2 L=O00BCE (Hex) , 003022 (Dec) +SMALL.FON - B=CE6F L=0093E (Hex) , 002366 (Dec) +MON_5X8.FON - B=CF03 L=0093E (Hex) , 002366 (Dec) +MONO .FON - B=CF97 L=00918 (Hex) , 002328 (Dec) +SYSSNORM. FON - B=D029 L=0093E (Hex) , 002366 (Dec) +SYSSBOLD.FON - B=DOBD L=0093E (Hex) , 002366 (Dec) +EXOPL. IMG - B=D151 L=002C0 (Hex) , 000704 (Dec) +OPLCH.DYL - B=D17D L=054C6 (Hex) , 021702 (Dec) +BATCHK. IMG - B=D6CA L=00750 (Hex) , 001872 (Dec) +TTEST.IMG - B=D73F L=00F40 (Hex) , 003904 (Dec) +PPRINT.IMG — B=D833 L=00850 (Hex) , 002128 (Dec) +CUSTOMS .DAT —- B=D8B8 L=01800 (Hex) , 006144 (Dec) + + +Rom Base Segment is 0A000 (Hex + + +) +Rom code size is 18150(Hex) 098640 (Dec) +Rom disk size is 22230(Hex) 139824 (Dec) +Free rom size is 05C60(Hex) 023648 (Dec) + + +Note that the length of each file listed is given by the "L" value - first in hex, then in decimal - and the +corresponding notional base address is given by the "B" value. + + +As can be seen, the amount of free space in the standard HC ROM is about 23k. However, this figure can +be increased by omitting some of the files normally included. + + +Some possibilities for customisation + + +An alternative shell +Rather than using corpshll.img, a customised version of the shell program may be substituted. + + +This alternative shell can have any suitable name (eg datashll.img), so long as the extension is .img and +the .rom file renames the shell to sys$shll.img. + + +See elsewhere in the HC Programming Guide for further details of writing a customised shell. + + +5-4 + + +5 CUSTOMISING THE HC ROM + + +Variant config files + + +Replacing cheng.cfo with chengel.cfo changes from the non-backlit variant to the backlit variant of the +keyboard table (in fact altering the value of the keycode returned to software when the middle of the three +salmon-coloured keys on the top row is pressed). + + +Similarly: +chfrn.cfo produces a ROM suited to the continental version of the keyboard, supporting +some accented characters such as é +chswe.cfo produces a ROM suited to the Scandinavian version of the keyboard, supporting +characters such as « +chnzl.cfo produces a ROM suited to the numeric version of the keyboard. + + +There are also files chfrnel.cfo, chsweel.cfo, and chnzlel.cfo, which are backlit variants of chfrn.cfo, +chswe.cfo, and chnzl.cfo. + + +Config files in .cfo format are produced from text format .fig files using the Psion proprietary tool +econfig.exe, details of which are available upon request. + + +Additional files that might be added + + +As many additional program (or data) files can be added as will fit in the rom. To make room for these +files, other files in the standard ROM may have to be omitted - see below. + + +Files that might be omitted + + +It is possible to omit any reference to sys$ntfy.img from the ROM file list provided that an alternative shell +is used. This shell must make a suitable call on start-up to wsystem so that the Windows server version of +the notifier is enabled. Alternatively suitable values must be written into sys$env.ini (see below). + + +The files ttest.img and pprint.img can each be omitted without any undue loss. + + +The file custom$.dat can be omitted if there is no intention to further customise individual HC roms +afterwards. Alternatively, a shorter form of this file can be substituted (every single byte in this file must +have the value oxf£). + + +The file batchk.img can be omitted or replaced with alternative battery checking software. In this case, it +is best not to use corpshil.img, as this emits an error message on start-up if it cannot locate and run a copy +of batchk.img. + + +The files exopl.img and oplch.dyl can be omitted if there is no need to run Opl programs on the HC. + + +Some of the .fon files can be omitted, provided due care is paid to provide a suitably adjusted sys$env.ini +(see below). For example, the MC-derived fonts big.fon, small.fon, and mono.fon could be omitted, +leaving only mon_5x8.fon and the Series3-derived fonts sys$norm.fon and sys$bold.fon. Note that the +order of listing .fon files in the .rom file defines which fonts correspond to which Window Server font +ids - wS_FONT_BASE specifying the first .fon file in the .rom listing, and so on. Note also that the HC +console (as used by C programs containing statements like puts or p_printf, and also by print +statements in Opl) presupposes the use of the third .fon file listed, so that this should always be +mono-spaced and of size 5 by 8. + + +Customising the Window Server + + +Whenever the system restarts, the Window Server reads the contents of sys$env.ini, and sets environment +variables according to the data therein. + + +Dumping the contents of the standard sys$env.ini will confirm that a particularly simple format is used in +this file: + + +[] + + +with this pattern being repeated as many times as there are environment variables to initialise. For each +such environment variable, the byte count preceding the environment variable name gives the length of +the name, and the byte count preceding the environment variable value gives the length of the value. + + +HC PROGRAMMING GUIDE + + +The only environment variables that you need to consider defining in sys$env.ini are the following: + + +$WS_SF gives (in two bytes) the index number of the .fon file to use as the "system" +font, which is the default font for all drawing via any GCs (graphics contexts). +This will usually be left at value 0, and as such can be omitted from sys$env.ini. + + +$WS_IF gives (in two bytes) the index number of the .fon file to use as the "internal" +font, which is what the Window Server uses when drawing alerts, busy +messages, and information messages. This has the value 4 in the standard +sys$env.ini, thereby specifying sys$norm.fon as the internal font. In case an +alternative .rom file omits big.fon and moves sys$norm.fon into this slot, the +value of sws_1F should be adjusted to 0. + + +$WS_FL gives (in two bytes) the initial value of the Window Server flags. This is zero in +the standard sys$env.ini. + + +See the System start-up section in the Window Server Reference manual for more details of the possible +Window Server flags. In many cases, the initial value 0x0a will be appropriate, setting the flags +_NO_NOTIFIER_REBOOT and _HOOK_NOTIFIER. + + +Creating and using a master SSD + + +Once a suitable .mas file has been created, the next step is to transfer it, together with the repro software, +onto a master SSD. This requires an SSD drive to be attached to the PC, although no special software +drivers (such as fefs.sys and devflash.sys) need to be installed. + + +Anyone ordering an SSD drive for their PC should note that, for it to function, not only is the drive itself +required, but also an ASIC-2 expansion card, and (in the case of an external SSD drive) a suitable +connecting cable. + + +The master SSD is usually created under the control of a batch file, of which the following +(makemast.bat) is an example: + + +@echo off + +emast —-ul v033eeng.mas + +echo Transferring other software... +xcopy \hcmast\*.* £:\*.* /s + + +This potentially copies a whole directory tree onto the master SSD, i.e. the contents of Vicmast\ including +subdirectories. In this case, the contents of Vicmast\ would include repro.app. + + +The batch file assumes that the PC sees the first SSD slot as drive £:, and would need to be altered if this +is not the case (changing f:\ to eg e:\). The batch file also assumes that all relevant software drivers for +the external SSD drives have been loaded. + + +The -u1 parameter to emast specifies that the top left SSD slot in the attached SSD drive is to be used. +The filename passed to emast obviously has to match that of the master file created earlier by erom. + + +Once the batch file has finished, the SSD can be used to repro HCs in the normal way. + + +More details on master SSDs + + +A master SSD must be a 512k Flash device and has a very special format: part of it is devoted to a "file" +that is outside the filing system proper, and the remainder (just under 256k) is presented to the outside +world as if it were the entirety of the SSD. + + +That is, normal file operations do not see the .mas "file" that is on the SSD. This is why the .mas file has +to be copied onto the SSD using a special tool, i.e. emast.exe. This tool not only copies on the .mas file but +also specially formats the remainder of the SSD. + + +To repro numeric keyboard HCs + + +To prepare a master SSD that can be used to repro an HC with a numeric keyboard (and which therefore +lacks keys such as R, E, P, and 0), a copy of repro.app should be renamed to yOn0.img before being copied +onto the master SSD. + + +5 CUSTOMISING THE HC ROM + + +Files required + + +This section lists the files from the Optional Disk of the SDK that are needed, in order to be able to +produce a customised ROM for the HC: + +source files: mrchy. bat, sch.rom, epochhp.exe, repro.app, makemast.bat, and the 22 files +listed above as the standard contents of a .rom file, i.e. cheng.cfo through +custom$.dat, together with the other 7 standard .cfo files + + +tools: erom.exe and emast.exe. + + +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 Solid State Disks Technical Specification + + +Dimensions + + +Size: 63mm (length) x 52mm (width) x 6mm (height) +Weight: =25¢ + +Capacities + +RAM: 128KB, 512KB, IMB, 2MB + +Flash: 128KB, 256KB, 512KB, IMB, 2MB, 4MB, 8MB +PSRAM: 512KB, IMB, 2MB + +Solo Flash: 128KB, 256KB, 512KB + +Filing System + +Flash, RAM and PSRAM: MS-DOS + +RAM and PSRAM: FAT directory/file system + +Interface + +Physical: 6 pin serial + +Electrical: Clock, OV, V, V_. V_., Data + + +backup’ ° pp’ * cc’? +Data Transfer + +SSD interface: 320Kbytes/sec + +File Access + + +Note: the quoted rates for the Series 3c also apply to the Siena with external SSD drive + + +All SSD types read: 30-40Kbytes/sec depending on SSD/directory structure (HC and Series 3c) +Flash write: =6Kbytes/sec (HC), =8Kbytes/sec (Series 3c) + +RAM and PSRAM write: 30-40Kbytes/sec depending on SSD/directory structure + +Formatting + +Flash: =30 secs per 128K (HC), =20 secs per 128K (Series 3c); 9,999 times minimum + + +Format/write voltage: 12V DC +Programming voltage: 15.0V to 18.0V DC on the Vh pin @ 40mA max. (type II flash) + + +RAM: 7.5 secs per 128K (HC), =6 secs per 128K (Series 3c) +Power + +Flash, standby: S500uA + +RAM, standby: 10uA + +Flash and RAM, reading: 1mA + +Flash, writing: 20-30mA + +RAM, writing: =ImA + + +HC PROGRAMMING GUIDE + + +PSRAM versus SRAM SSDs + + +Important: Pseudo-Static RAM (PSRAM) SSDs are not recommended for use in consumer machines, +(Series 3a, Series 3c and Siena). This section explains why. + + +PSRAM SSD's are not suitable for use with some machines: +HC Yes (with an upgrade - see below) + + +HC-DOS Yes (with an upgrade - see below) + + +Workabout + + +Series 3 (all variants) + + +Series 3a 256K, 512K + + +i + + +The fact that PSRAM SSDs can only be used with the IMB and 2MB Series 3a is effectively a No to the +Series 3 range, because of the problem of having to differentiate the various Series 3 models at point of +sale. PSRAM SSDs are therefore only recommended for use in Psion Industrial’s handhelds. + + +An upgrade to both HC and HC-DOS machines (involving a component change on the main PCB only) +is in progress. HC and HCDOS machines supporting PSRAM SSDs will be identifiable by their serial +number. The performance of the upgraded machines is not affected in any other way, including power +consumption and use with any peripherals and other SSD types. + + +All SSD's have a common serial interface which sets the data transfer rate. This means that for reading +and writing data, all types of RAM SSDs work at the same speed. + + +The power consumption of a PSRAM chip is generally higher than for the equivalent Static RAM +(SRAM) chip when read/writing data. However, both types of memory only transfer data during a small +part of the SIBO cycle so the power consumption of an active SSD is not much higher for a PSRAM as +opposed to an SRAM. + + +However, a PSRAM SSD consumes a significant amount of current when the host machine is turned on, +even though no data is being transferred. This is because an oscillator is required to refresh the +memory. This can increase the overall current consumption of the machine by up to a third. Also, when +the host machine is off, the backup current of the PSRAM SSD is much higher than the equivalent +SRAM SSD. A lithium cell in a 2MB PSRAM will have a life of about 17 days (400 hours) outside a +SIBO machine. PSRAM SSDs are best considered as memory expansion rather than removable media +and are most suited to applications where they remain inside a machine; then they only rely on their +backup batteries when the machine's main battery is changed. + + +PSRAM SSDs should therefore only be used in applications where the above disadvantages have little +affect. An example is a Workabout which is mostly powered/recharged through insertion into a docking +station and whose SSDs are never removed. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Psion HC Technical Specification + + +Models + + +Psion HC100: +Psion HC110: +Psion HC120: + + +128K CMOS static RAM. +256K CMOS static RAM. +512K CMOS static RAM. + + +All models have 256K internal Flash ROM. + + +Processor + + +Type: +Clock: + + +Dimensions + + +Size: +Weight: + + +Environmental + + +Temperature: +Humidity: +Weatherproofing: +Drop resistance: +EMC: + +Safety: + + +Software + + +Operating system: + + +Command shell: + + +Communications: + + +Printing: + + +Solid State Disks + + +Built-in drives: +SSD capacities: + + +Filing system: + + +File Access + + +80C86-compatible 16-bit processor. +3.84MHz. + + +200mm (length) x 80mm (width) x 35mm (height). +395g (540g with batteries but no SSDs). + + +Operating OC to +50C, storage -20C to +70C. +Operating 90% max non-condensing. + +IP54. Splashproof (depending on variant). + +1 metre onto concrete. + +FCC Class B; CE marked, E-marked. +EN60950. + + +Psion EPOC multitasking OS. + +MS-DOS like command interpreter + +Psion LINK, 50-9600 baud, asynchronous, + +compatible with MCLINK, RCOM & PSIWIN software on remote PC. +Parallel and serial and via remote PC. + + +Two SSD drives. + +Flash: 128KB, 256KB, 512KB, IMB, 2MB, 4MB, 8MB +RAM: 128KB, 512KB, 1MB, 2MB. + +MS-DOS compatible. + + +Note: the quoted rates apply only to the HC. + + +Flash read: +RAM read: +Flash write: +RAM write: + + +Formatting +Flash: + + +Format/write voltage: + + +RAM: +Screen +Type: + + +Resolution: +Dimensions: + + +Keyboard + + +Alphanumeric: +Numeric: +Custom: + + +30-40Kbytes/sec depending on SSD/directory structure. +30-40Kbytes/sec depending on SSD/directory structure. +~6Kbytes/sec. + +30-40Kbytes/sec depending on SSD/directory structure. + + +=30 secs per 128K. +12V DC. +7.5 secs per 128K. + + +Black and white retardation film LCD, optional back lighting. +160 X 80 pixels, 26 characters x 9 lines (default font). +60mm (width) x 50mm (height). + + +53 key UK/US, European and Scandinavian versions. +31 key with function keys. +Can be provided. + + +HC PROGRAMMING GUIDE + + +Sound +Built-in: +Power + + +Main battery: +Back-up: +External: +Battery life: + + +Expansion + + +Capabilities: +Modules: + + +Piezo buzzer (single tone) and loudspeaker. + + +NiCad 500mAH or 600mAH rechargeable pack. + +CR1620 3V lithium cell. + +12V DC via Psion adaptor. + +Typically up to 50 hours, depending on use and configuration. + + +Two expansion module interfaces. + +RS232/Parallel; Quad Modem; MCR/RS232/TTL-RS232; Bar Code Reader; +RS232/TTL-RS232; RS232/Bar Code Reader; Printer; LIF-PFS/Barcode; +LIF-PFS/TTL-RS232; 16550 RS232/TTL-RS232; Vehicle/TTL-RS232; +Integral Laser Scanner. + + +Psion HC RS232/Parallel (printer) module, version 1 +Technical Specification + + +Important Notice - Compatibility + + +This module can continue to be used in both top and bottom ports of the HC. Applications requiring +serial or parallel comms from the HC should use this module. + + +This module can be used in the Workabout Docking Station for serial or parallel communications. + + +This module must not be used in an HC Docking Station sold in countries requiring the CE Mark. The +version 2 Psion HC RS232/Parallel (printer) module must be used instead. + + +Physical + + +Part number: +Module: + + +HC compatibility +HC-DOS compatibility + + +Docking station compatibility + + +EMC: + + +Safety + + +Connectors +RS232: + + +Parallel: + + +Serial Interface +Baud: + + +Data bits: + +Stop bits: + +Parity: +Handshaking: +Remote switch-on +Protocols: + + +1502-0001 +Integrated removable module. + + +Yes. Fits into either of the HC's expansion ports. +Yes + + +Not CE marked configuration - version 2 model required + + +FCC Class B, CE-mark and E-marknot CE marked for use with HC +Docking Station + + +EN60950 + + +9 way miniDIN female. + + +Standard Centronics 25 way D female + + +50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, +9600. + +5, 6, 7, 8 (ASCID). + +1,2 + +Odd, even, none. + +XON/XOFF, RTS/CTS, DSR/DTR, DCD. + +Via DSR line (optional). + +Psion proprietary MCLINK protocol. + +Xmodem protocol. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +RS232 interface + + +Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The +difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. +This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board +link. + + +RS232 , (9 way male D-type), pinout + + +Pin 1: DCD input. + +Pin 2: RX input. + +Pin 3: TX output. + +Pin 4: DTR output. + +Pin 5: Ground (OV). + +Pin 6: DSR input. + +Pin 7: RTS output. + +Pin 8: CTS input. + +Pin 9: Optional VSUP input/output, (7-10V DC). DC input must not exceed 10V. + + +Parallel Interface + + +Parallel Interface pinout + + +Pin | Strobe output +Pin 2 Data 0 output +Pin 3 Data 1 output +Pin 4 Data 2 output +Pin 5 Data 3 output +Pin 6 Data 4 output +Pin 7 Data 5 output +Pin 8 Data 6 output +Pin 9 Data 7 output +Pin 10 ACK input + +Pin 11 BUSY input +Pin 12 PE input + +Pin 13 NC + +Pin 14 AUTO FD XT output +Pin 15 ERROR input +Pin 16 INIT output + +Pin 17 SLCT IN output +Pins 18-25 Ground 0V + + +Psion HC RS232/Parallel (printer) module, version 2 +Technical Specification + +Important Notice - Compatibility + +This module must be used in the HC Docking Station for countries requiring the CE Mark. + + +This module is compatible with all configurations of Psion HC, HC Docking Station and Workabout +Docking Station and is recommended for all new installations. + + +HC PROGRAMMING GUIDE + + +Physical + + +Part number: +Module: + + +HC compatibility + + +HC-DOS compatibility + + +1502 0052 10 +Integrated removable module. + + +Yes. Fits into either of the HC's expansion ports. +Yes + + +Docking station compatibility Yes + + +EMC: +Safety: + + +Connectors +RS232: + + +Parallel: + + +Serial Interface + + +Baud: + +Data bits: + +Stop bits: + +Parity: +Handshaking: +Remote switch-on +Protocols: + + +RS232 interface + + +FCC Class B, CE-mark and E-mark +EN60950 + + +9 way male D-type (RS232, PC AT type). + + +15 way High Density D male. A 15 Way to 25 Way converter cable is +required for connection to a standard Centronics port. + + +50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, +9600. + +5, 6, 7, 8 (ASCID). + +1,2 + +Odd, even, none. + +XON/XOFF, RTS/CTS, DSR/DTR, DCD. + +Via DSR line (optional). + +Psion proprietary MCLINK protocol. + +Xmodem protocol. + + +alin) MC EXPANSION MODULI + + +PARALLEL / SERIAL PORTS + + +MADE INTHE UK + + +PRINTER & PARALLEL PORT AS 232 SERIAL + + +Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The +difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. +This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board + + +link. + + +RS232 , (9 way male D-type), pinout + + +Pin |: +Pin 2: +Pin 3: +Pin 4: +Pin 5: +Pin 6: +Pin 7: +Pin 8: +Pin 9: + + +DCD input. + +RX input. + +TX output. + +DTR output. + +Ground (OV). + +DSR input. + +RTS output. + +CTS input. + +Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +15 way High Density Parallel Interface +15 way High Density Parallel socket (male) + + +15 way High Density Parallel Interface pinout + + +Pin | +Pin 2 +Pin 3 +Pin 4 +Pin 5 +Pin 6 +Pin 7 +Pin 8 +Pin 9 +Pin 10 +Pin 11 +Pin 12 +Pin 13 +Pin 14 +Pin 15 + + +Strobe output +Data 0 output +Data 1 output +Data 2 output +Data 3 output +Data 4 output +Data 5 output +Data 6 output +BUSY input +ERROR input +INIT output +SLCT IN output +Data 7 output +PE input +Ground 0V + + +Psion 15 Way to 25 Way converter cable +Technical Specification + + +Physical + + +Part number: + + +Length: +EMC: + + +Safety: + + +Connectors + + +15-way parallel: + + +25-way parallel: + + +2403 0026 01 + + +30cm. +FCC Class B, CE-mark and E-mark + + +EN60950 + + +female; for connection to the 15-way high-density parallel (printer) socket on +the Psion HC RS232/Parallel (printer) module, version 2 + + +for connection to a standard Centronics port on a printer. + + +HC PROGRAMMING GUIDE + + +15 way High Density Parallel plug (female) + + +15 way High Density Parallel Interface connector pinout + + +Pin | Strobe output +Pin 2 Data 0 output +Pin 3 Data 1 output +Pin 4 Data 2 output +Pin 5 Data 3 output +Pin 6 Data 4 output +Pin 7 Data 5 output +Pin 8 Data 6 output +Pin 9 BUSY input +Pin 10 ERROR input +Pin 11 INIT output +Pin 12 SLCT IN output +Pin 13 Data 7 output +Pin 14 PE input + +Pin 15 Ground 0V +25-way connector pinout + +Pin | Strobe output +Pin 2 Data 0 output +Pin 3 Data 1 output +Pin 4 Data 2 output +Pin 5 Data 3 output +Pin 6 Data 4 output +Pin 7 Data 5 output +Pin 8 Data 6 output +Pin 9 Data 7 output +Pin 10 NC + +Pin 11 BUSY input +Pin 12 PE input + +Pin 13 NC + +Pin 14 NC + +Pin 15 ERROR input +Pin 16 INIT output +Pin 17 SLCT IN output +Pins 18-25 Ground 0V + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Psion HC MCR /RS232 /TTL RS232 module, (Version 2), +Technical Specification + + +Physical + + +Part number: +Module: + + +HC compatibility +HC-DOS compatibility + + +1502-0003 +Integrated removable module. + + +Yes. Fits into either of the HC's expansion ports. +No + + +Docking station compatibility Yes + + +Certification: + + +MCR Interface + + +Connections +Socket: +Readers supported: + + +MCR unit power supply: + + +Pinout + +Plug required: +Pin 1: + +Pin 2: + +Pin 3: + + +Pin 4: +Pin 5: + + +Pin 6: +Pin 7: + + +FCC Class B +VDE Class B + + +7 way locking miniDIN female. +Single or simultaneous two track reader. + + +5V DC output available to power MCR unit. This is software switchable. + + +Hosiden type TCP6170-1100 or equivalent. +SV output (100mA max). +CLD. Card load input (low when card in reader). 100k pullup to 5V. + + +DATALIL. Data input for track | reader. Data is read in on falling edge of the +clock line. 100k pullup to 5V. +CLOCK 1. Clock input for track 1 reader. 100k pullup to 5V. + + +DATA2. Data input for track 2 reader. Data is read in on falling edge of the +clock line. 100k pullup to 5V. +CLOCK2. Clock input for track 2 reader. 100k pullup to 5V. + + +Ground. (OV). + + +RS232 / RS232 TTL Interface + + +Connections + + +The single RS232 interface can be software switched between 2 sockets. + + +Sockets: + + +Interface + + +Baud: + +Data bits: + +Stop bits: + +Parity: +Handshaking: +Remote switch-on +Protocols: + + +8 way locking miniDIN socket (RS232 TTL). +9 way miniDIN socket (standard RS232). + + +50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, +9600. + +5, 6, 7, 8 (ASCID). + +1.2. + +Odd, even, none. + +XON/XOFF, RTS/CTS, DSR/DTR, CDC. + +via DSR line (optional). + +Psion proprietary MCLINK protocol. + +Xmodem protocol. + + +HC PROGRAMMING GUIDE + + +RS232 TTL socket + +TTL levels: 0-5V. + +TTL signals: TX, RX, RTS, CTS, DSR., plus software switchable unregulated 7-10V DC +and regulated SV DC. + +TTL polarity: Programmable in software. + +Readers supported: This interface is intended for use with peripherals such as low power laser + + +and CCD bar code scanners which support a TTL level RS232 interface. + + +Scanner power supply: Unregulated 7-10V DC and regulated 5V DC to power the scanner. These +are software switchable. + + +RS232 TTL socket pinout + + +Plug required: Hosiden type TCP6180-1100 or equivalent. + +Pin 1: 5V DC regulated output. (250mA max*). + +Pin 2: TX output. TTL transmit. + +Pin 3: RTS output. TTL handshaking. + +Pin 4: VSUP output. Unregulated 7-10V DC output (250mA max*). +Pin 5: RX input. TTL receive. + +Pin 6: CTS input. TTL handshaking. + +Pin 7: DSR input. TTL handshaking. + +Pin 8: Ground. (OV). + + +*The maximum combined current must not exceed 250mA + + +Standard RS232 interface + + +Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference +between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. This pin on the +HC can be optionally connected to the HC VSUP input/output supply via an on board link. + + +RS232 , (9 way male D-type), pinout + + +Pin 1: DCD input. + +Pin 2: RX input. + +Pin 3: TX output. + +Pin 4: DTR output. + +Pin 5: Ground (OV). + +Pin 6: DSR input. + +Pin 7: RTS output. + +Pin 8: CTS input. + +Pin 9: Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. + + +Psion HC RS232 /TTL RS232 module, +Technical Specification + + +Note: a 16550 RS232/TTL-RS232 module is also available and is described later in this Appendix. + + +Physical + +Part number (IP64): 1502-0039 + +Part number (non-IP64): 1502-0040 + +Module: Integrated removable module. + +HC compatibility Yes. Fits into either of the HC's expansion ports. +HC-DOS compatibility Yes + + +Docking station compatibility Yes + + +EMC: +Safety +Weatherproofing: + + +Connections + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +FCC Class B, CE-mark and E-mark +EN60950 + + +IP64 (depending on model, see part number above) + + +The single RS232 interface can be software switched between 2 sockets. + + +Sockets: + + +Peripherals supported: + + +RS232 interface + + +Baud: + +Data bits: + +Stop bits: + +Parity: +Handshaking: +Remote switch-on +Protocols: + + +RS232 TTL interface +TTL levels: + +TTL signals: + +TTL polarity: + +Power supply outputs: + + +Power supply inputs: + + +RS232 interface + + +9 way female D-type +9 way male D-type + + +(RS232 TTL). +(RS232, PC AT type). + + +The TTL RS232 interface is intended for use with peripherals such as low +power laser and CCD bar code scanners which support a TTL level interface. + + +50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, +9600. + +5, 6, 7, 8 (ASCII). + +1, 2. + +Odd, even, none. + +XON/XOFF, RTS/CTS, DSR/DTR, CDC. + +via DSR line (optional). + +Psion proprietary MCLINK protocol. + +Xmodem protocol. + + +0-5V. + +TX, RX, RTS, CTS, DSR., plus software switchable. + +Programmable in software. + +Software switchable unregulated 7-10V DC, unswitched unregulated +7-10V DC and regulated SV DC. + + +The unswitched 7-10V pin is directly connected to the HC main power rail +and can therefore be used to power the HC. To do this the supply coming +into the HC must be diode isolated (so as not to take power from the HC) +and in the range 7-10V (1OV maximum). NOTE: powering the HC from +this pin will not charge the HC internal battery. + + +Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The +difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. +This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board +link. This is described above. + + +RS232 , (9 way male D-type), pinout + + +Pin |: +Pin 2: +Pin 3: +Pin 4: +Pin 5: +Pin 6: +Pin 7: +Pin 8: +Pin 9: + + +DCD input. + +RX input. + +TX output. + +DTR output. + +Ground (OV). + +DSR input. + +RTS output. + +CTS input. + +Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. + + +HC PROGRAMMING GUIDE + + +RS232 TTL interface +RS232 TTL socket pinout + + +Pin |: +Pin 2: +Pin 3: +Pin 4: +Pin 5: +Pin 6: +Pin 7: +Pin 8: +Pin 9: + + +VSUP switched output. Unregulated 7-10V DC output (250mA max*). + +RX input. TTL receive. + +TX output. TTL transmit. + +SV output. (250mA max*). + +Ground (OV). + +DSR input. TTL handshaking. + +RTS output. TTL handshaking. + +CTS input. TTL handshaking. + +VSUP Input/output. 7-10V DC input/output. DC input must not exceed 10V. + + +*The maximum combined current must not exceed 250mA + + +Psion HC 16550 RS232 /TTL-RS232 module, +Technical Specification + + +Note: an ASICS based RS232/TTL-RS232 module is also available, and is described above. + + +This module may be used with any standard HC (or HCDOS machine) for faster data transfer +rates than the standard module. The essential difference between this module and the standard +"RS232 / TTL-RS232" module is that a 16550 UART is used rather than the ASIC5 UART + +used in the standard module. Also the RI (Ringing Indicator) function is provided to make it a true +IBM PC-AT RS232 interface (note that the HC software does not make any use of RI ). + + +Physical +Part number +Module: + + +Operating temperature +Storage temperature +Weight + +HC compatibility +HCDOS compatibility + + +1502-0045 + + +Integrated removable module. +Fits into either of the HC's expansion ports. + + +-20 to +60 °C + +-20 to +60 °C + +60g + +Yes, loadable PDD required +Yes + + +Docking Station compatibility No + + +Emissions +Connections + + +FCC class A + + +The single RS232 interface can be software switched between 2 sockets. + + +Sockets: + + +Peripherals supported: + + +9 way female D-type (RS232 TTL). +9 way male D-type (RS232, PC AT type; full EIA-232 signal levels). + + +The TTL RS232 interface is intended for use with peripherals such as low +power laser and CCD bar code scanners which support a TTL level RS232 +interface. The polarity of this interface can also be programmed to be +standard (non-inverting) or inverting. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +RS232 interface + + +Baud: 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, +9600, 19200; also 38400 using error corrected transmission. + +Data bits: 5, 6, 7, 8 (ASCII). + +Stop bits: 1, 2. + +Parity: Odd, even, none. + +Handshaking: Xon/Xoff, RTS/CTS, DSR/DTR, CDC. + +Remote switch-on via DSR line (optional). + +Protocols: Psion proprietary MCLINK protocol. + + +Xmodem protocol. + + +RS232 TTL interface + + +TTL levels: 0-5V. + +TTL signals: TX, RX, RTS, CTS, DSR., plus software switchable. + +TTL polarity: Programmable in software. + +Power supply outputs: Software switchable unregulated 6-10V DC, unswitched unregulated +6-10V DC and switched regulated 5V DC. + +Power supply inputs: The unswitched 7-10V pin is directly connected to the HC main power rail + + +and can therefore be used to power the HC. To do this the supply coming +into the HC must be diode isolated (so as not to take power from the HC) +and in the range 7-10V (OV maximum). + +NOTE: powering the HC from this pin will not charge the HC internal +battery. + + +HC usage + + +A loadable software Physical Device Driver (PDD) is available to allow this module to be used on any +standard HC. Once this driver is loaded the module is accessed exactly the same as the current ASICS +based RS232/TTL-RS232 module. + + +When fitted it allows the HC to reliably communicate at 19200 baud (the standard module is only +reliable up to 9600 baud). However when using error corrected protocols such as LINK, communicating +at 38400 baud is feasible. In tests file transfer rates in excess of 2Kbytes/second have been achieved +using LINK in conjunction with MCLINK on a 486 PC. + + +Docking station usage + + +The HC/HCDOS communicates with this module via the parallel expansion bus, therefore it cannot be +plugged into a Docking Station. + + +HCDOS usage + + +Baud rates of up to 115,200 are achievable compared with a maximum of 19,200 for the standard +module. + + +Connector selection and TTL polarity selection will normally be under application control but the +HCSETUP utility can be used. The port appears as COM1 if the module is plugged into the top HCDOS +expansion slot or COM2 in the bottom slot. + + +RS232 interface + + +Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The +difference between this socket and an IBM AT is that the RI (ringing indicator) pin can be optionally +connected to the HC VSUP input/output supply via an on board switch. This is described below. + + +RS232 , (9 way male D-type), pinout + + +Pin I: DCD input. +Pin 2: RX input. +Pin 3: TX output. +Pin 4: DTR output. +Pin 5: Ground (OV). +Pin 6: DSR input. + + +HC PROGRAMMING GUIDE + + +Pin 7: RTS output. +Pin 8: CTS input. +Pin 9: RI input or + + +VSUP Input. 7-10V DC input. DC input must not exceed 10V. or + + +VSUP Output. 6-10V DC unregulated. 250mA maximum current, or 200mA +maximum current if another expansion module is also being powered. + + +See below for full details. + + +Pin 9 RI / VSUP switch + + +If you hold the module with the component side of the PCB facing you and the D-type connectors at the +top, this switch is located below the right hand D-type connector. + + +Important: the normal position for this switch is 'RI' (in the left hand position), it should only be +switched to the 'VSUP' position for special applications as described below otherwise damage +could occur to either the HC or the device connected at the other end. + + +The 'VSUP’ connection should be selected only if one of the following is required: + + +1. The HC is to be powered externally. The supply applied to the HC must be diode isolated (to +prevent power drain from the HC) and in the range 7-10V (1OV maximum). +NOTE: powering the HC from this pin will not charge the HC internal battery. + + +2. The HC is required to supply power to another device, for example certain true RS232 I/F laser +scanners require power to be supplied from the RS232 connector. Note that VSUP is not software +switchable and is present even when the HC is switched off, so the device would need its own +ON-OFF switch to prevent the HC battery being drained when the device is not in use. + +VSUP is an unregulated supply in the range 6-10V. The device powered from pin 9 should not +draw more than 250mA from VSUP if no other expansion modules are powered up +simultaneously (if another expansion module is fitted and powered up, the current drawn should +not exceed 200mA). + + +DSR auto-wakeup switch + + +If you hold the module with the component side of the PCB facing you and the D-type connectors at the +top, this switch is located to the bottom left hand corner of the PCB. If this switch is ON (in the right +hand position) the HC is automatically turned on when DSR is asserted by the device connected to the +RS232 port. + + +Power consumption + + +When the RS232 port is open it typically draws 8mA plus the current drawn by the device connected at +the other end, this will vary depending on the device, for example connected to a PC the total current +drawn will increase to typically 18mA (this however will vary from one PC to another). + + +TTL interface +RS232 TTL socket pinout, (9 way female D-type) + + +Pin 1: VSUP switched output. Unregulated 6-10V DC output (250mA max*). +Pin 2: RX input. TTL receive. + +Pin 3: TX output. TTL transmit. + +Pin 4: Switched 5V output. (250mA max*). + +Pin 5: Ground (OV). + +Pin 6: DSR input. TTL handshaking. + +Pin 7: RTS output. TTL handshaking. + +Pin 8: CTS input. TTL handshaking. + +Pin 9: VSUP Input. 7-10V DC input. DC input must not exceed 10V. or + + +VSUP Output. 6-10V DC unregulated. 250mA maximum current*, or +200mA maximum current* if another expansion module is also being +powered. + + +*The maximum combined current must not exceed 250mA + + +A-14 + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Switched VSUP (pin 1) and 5V (pin 4) outputs + + +Both these switched power supply outputs are provided to power peripherals plugged into the TTL +connector and both are enabled only when the port is open and TTL connector is selected. + + +VSUP is an unregulated supply in the range 6-10V. +The 5V regulated output has a tolerance of +/- 5%. + + +The device powered from either supply should not draw more than 250mA if no other expansion +modules are powered up simultaneously (if another expansion module is fitted and powered up, the +current drawn should not exceed 200mA). If current is drawn from both rails then the combined current +should not exceed 250mA (or 200mA if another module is present). + + +VSUP direct connection (pin 9) + + +A direct VSUP connection is also provided for the same purposes as the VSUP option on pin 9 of the +RS232 connector, see description above. + + +Power consumption + + +When the port is open and the TTL interface is selected, the interface typically draws 5mA. In most +cases however the current drawn by the peripheral device dominates. + + +Psion HC Bar Code Reader module, (Version 2), +Technical Specification + + +Physical + +Part number (HP wand): 1502-0020 + +Part no. (Welch Allen wand): 1502-0021 + +Module: Integrated removable module. + +HC compatibility Yes. Fits into either of the HC's expansion ports. + +HC-DOS compatibility No + +Docking station compatibility No + +Certification: FCC Class A + +VDE Class B + +Connection + +Socket: 6 way locking miniDIN socket. + +Peripherals supported: Will support most standard bar code wands and also scanners with wand +emulation output. It is supplied with one of either: +HP wand HPBCS-A207 and plug or +Welch Allen wand and plug + +Remote switch-on: Facility for remotely switching machine on with bar code wand or scanner. + +Power supply output: 5V DC available to power a wand or scanner. This is software switchable. + +Pinout + +Plug required: Hosiden type TCP6160-1100 or equivalent. + +Pin 1: EXON. Turns HC on when pulled low. 100k pullup to 5V present at all +times (even if machine is switched off) + +Pin 2: Enable output. Optional output to barcode device. Under software control +(application dependant). + +Pin 3 Switch input. Optional input for barcode switch. + +Pin 4: Data input. Input from barcode wand. 2k2 pullup to 5V when reading +from wand. + +Pin 5: SV output. (Max 250mA) + +Pin 6: Ground. (OV) + + +HC PROGRAMMING GUIDE + + +Psion HC RS232 / Bar Code Reader module, +Technical Specification + + +This module combines a standard RS232 interface via a 9 way male D-type (PC-AT type) connector +with a bar code interface via a 9 way male D-type click-lock connector. + + +Physical + +Part number 1502-0044 + +Module: Integrated removable module. +Operating temperature: -20 to +60 °C + +Storage temperature: -20 to +60 °C + +Weight: 62g + +HC compatibility Yes. Fits into either of the HC's expansion ports. +HC-DOS compatibility Yes + +Docking station compatibility Yes + +EMC: FCC Class B, CE-mark and E-mark +Safety EN60950 + +Weatherproofing: No + + +RS232 interface +The RS232 interface is accessed by opening TTY:A (top slot) or TTY:B (bottom slot). + + +It provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The +difference between this socket and an IBM AT is that the RI (ringing indicator) pin (pin9) is not +implemented. This pin can be optionally connected to the HC VSUP main power supply rail by fitting a +jumper to the 2-pin header on the PCB (described below). + + +Connection + +Socket: 9 way male D-type (PC-AT type) + +Peripherals supported: Will support most standard bar code wands and also scanners with wand +emulation output. + +Remote switch-on: Facility for remotely switching machine on. Selectable by switch on PCB; +see below. + +Power supply input: Optional VSUP connection, (7-10V DC unregulated), to power the HC; +see below. + +Power supply output: Optional VSUP connection, (6-10V DC unregulated), available to power a +wand or scanner; see below. + +Pinout + +Pin 1: DCD input + +Pin 2: RX input. + +Pin 3: TX output. + +Pin 4: DTR output. + +Pin 5: Ground (Ov) + +Pin 6: DSR input. + +Pin 7: RTS output. + +Pin 8: CTS input. + +Pin 9: Optional VSUP connection. See below. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Pin 9 VSUP connection + + +The jumper should be fitted to make this connection only if one of the following is required: + + +e The HC is to be powered externally. The supply applied to the HC must be diode isolated (to +prevent power drain from the HC) and in the range 7-10V (10V maximum). +NOTE: powering the HC from this pin will not charge the HC internal battery. + + +e The HC is required to supply power to another device, for example certain true RS232 I/F laser +scanners require power to be supplied from the RS232 connector. Note that VSUP is not software +switchable and is present even when the HC is switched off, so the device would need its own +ON-OFF switch to prevent the HC battery being drained when the device is not in use. + +VSUP is an unregulated supply in the range 6-10V. The device powered from pin 9 should not +draw more than 250mA from VSUP if no other expansion modules are powered up +simultaneously. If another expansion module is fitted and powered up, the current drawn should +not exceed 200mA. + + +Warning: the jumper should not be fitted in any other circumstance, to prevent damage to the device +connected or to the HC. + + +DSR auto-wakeup switch + + +If you hold the module with the component side of the PCB facing you and the D-type connectors at the +top, the switch is located to the bottom left hand corner of the PCB. If this switch is ON (in the left +hand position) the HC is automatically turned on when DSR is asserted by the device connected to the +RS232 port. + + +Power consumption + + +The RS232 port is only powered up when the appropriate channel is open. Typically the interface draws +10mA plus the current drawn by the device connected at the other end, this will vary depending on the +device, for example connected to a PC the total current drawn will increase to about 20mA (this +however will vary from one PC to another). + + +Bar code interface + + +The interface to the Bar code decoder is via RS232 serial signals. It is accessed by opening TTY:D(top +slot) or TTY:E (bottom slot). The port is powered up and down by opening and closing the appropriate +channel. + + +Decoder +Decoder IC: +Input speed: + + +Hewlett Packard HBCR-1612 +9600 Baud via serial + + +Input data: + + +Discrimination: + + +Supported symbologies: + + +Maximum scan speed: + + +Output data: +Peripherals supported: +Unsupported scanners: + + +Programming: + + +8 Data bits, 1 Stop Bit + +Automatic + +Code 39 (standard or extended) +Interleaved 2 of 5 + +UPC A, EO, E1 (with supplemental digits) +EAN/JAN 8,13 (with supplemental digits) +Codabar + +Code 128 + +30 ips (76 cm/s) + + +By default when a successful bar code is read the number is transmitted to +the HC in ASCII format followed by a carriage return. + + +Will support most standard bar code wands and also scanners with wand +emulation output. + + +"Undecoded Laser Scanner' ( also known as HHLC, hand held laser +compatibility). + + +The HBCR-1612 is programmable via escape sequences. For more detailed +programming information refer to the //O Devices Reference manual. + + +HC PROGRAMMING GUIDE + + +Connection + +Socket: 9 way male D-type click-lock + +Power supply outputs: VSUP connection, (6-10V DC unregulated), and 5V DC regulated, available +to power a wand or scanner. See below. + +Pinout + +Pin 1: DCD input + +Pin 2: Bar Data input + +Pin 3: No connect + +Pin 4: Switched VSUP (6-10V DC) output*. + +Pin 5: DSR input + +Pin 6: DTR output. + +Pin 7: Ground (OV) + +Pin 8: Ground (OV) + +Pin 9: Switched 5V regulated output*. + + +VSUP and 5V regulated outputs + + +Both these switched power supply outputs are provided to power devices plugged into the bar code port +and both are enabled only when the appropriate channel is open. + + +VSUP is an unregulated supply in the range 6-10V. +The 5V regulated output has a tolerance of +/- 5%. + + +*The device powered from either supply should not draw more than 250mA if no other expansion +modules are powered up simultaneously. If another expansion module is fitted and powered up, the +current drawn should not exceed 200mA. If current is drawn from both rails then the combined current +should not exceed 250mA (or 200mA if another module is present). + + +Power consumption + + +The Bar code port is only powered up when the appropriate channel is open. Typically the interface +draws 10mA idle plus any current drawn by the wand. During a scan the interface typically draws +24mA plus the current drawn by the wand. Current drain varies greatly from one wand to another and +choice of wand can have a considerable effect on battery life. + + +Note + + +HC bar code readers may be converted for use with the Psion Workabout. See Appendix A - Technical +Specifications in the Workabout Programming Guide manual. + + +Psion HC Modem UK module, +Technical Specification + + +Physical + +Part number: 2400-0090-01 + +Module: Integrated removable module. + +HC compatibility Yes. Fits into either of the HC's expansion ports. +HC-DOS compatibility No + + +Docking station compatibility Yes + + +Certification: BABT approved in UK (approval number NS/1397/3/T/605 141) +BS6301 (safety) + + +Power: 70mA maximum + + +Environment + + +Operating temperature: +Operating humidity: + + +Communication modes + + +V standards: +Operational modes: + + +Data transfer rate: + + +Network connection + + +Line connection: + + +Signal level: +Equalisation: +Interface: +REN: + + +Autodial/autoanswer + + +Dial method: + +Call progress: + +Call control: + +Auto answer: +Mode selection: +Call disconnection: + + +Data interface +DTE interface: +Command buffer: +Protocol: + + +DTE speed: +Error correction: + + +Diagnostics + + +Test modes: + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +0 - 50C +0 - 96% non-condensing + + +V21, V22, V22bis, V23. +V22bis 2400 bps full duplex. +V22 1200 bps full duplex. +V23 1200/75 bps full duplex. +V23 75/1200 bps full duplex. +V21 300 bps full duplex. + +Up to 2400 bps with V22bis. + + +BT 600 series jack for 2 wire PSTN, + +3 wire bell tinkle suppression supported + +-9dBm. + +Transmit - fixed compromise, receive - automatic adaptive. +600Q + +1 + + +Pulse and tone dialling. + +Internal loudspeaker with volume control, extended results codes. +Extended Hayes AT command set. + +To ITU-T (CCITT) V25 recommendation, with echo suppression. +Automatic configuration to V23/V22bis/V22/V21 on receive. +Loss of carrier, DTR or by command. + + +Psion high speed serial + +Compliant with V24/V28 TX, RX, RTS, CTS, DSR, DCD, DTR, RI +40 characters + +Async command and data mode. + +300, 600, 1200 and 2400bps. + +V42 including LAPM and MNP Class 4. + + +V54 digital and analogue loops. + + +Psion HC Vehicle Interface Box Technical Specification + + +This unit is designed to be mounted in a vehicle and provide the following functions: + + +e DC power regulation and protection. + + +e §6°=Wiring interfacing. + + +e Direct connection to the RS232 interface. + + +The unit and cables have E-Mark certification. + + +The wiring connections, (as shown in the system block diagram below), are: + + +e Unregulated 10-18 volts input from the vehicle source, (‘Vehicle Supply’). + + +e RS232 serial interface to a radio or telephone modem, ('RS232'). +e RS232 to/from the HC, power, trickle charge for the battery, ((RS232 and Power’). + + +Note that the HC Vehicle Interface Box does not support the Psion Workabout range; see Appendix A in +the Workabout Programming Guide manual for a description of the Workabout VIC (Vehicle Interface + + +Cradle). + + +The HC needs to be fitted with a special LIF-PFS/TTL-RS232 expansion module. + + +HC PROGRAMMING GUIDE + + +ooo === + + +O00000) + + +OO0000) Vehicle Supply + + +oOo00o00 + +DOoo000 + +poo50 —— + +Bonn” RS 232 ry + +iJ and Power 5 1 RS 232 +2 O° ,— + +l oo 0 + + +HC Computer Vehicle Interface Box Radio/Modem + + +System block diagram + + +LED Indicator + + +9 Way D type (Male) connector 15 Way D type (Female) connector +and 2 way Power input + + +End views of the HC Vehicle Interface Box showing the connectors + + +The Vehicle Interface kit includes: +e Vehicle Interface Box, Part Number 2400-0079. + + +e =A LIF - RS232 cable 1.5m length, terminated at one end with a LIF connector +(Polarisation Type A) and a 15 way D type connector at the other. +LIF - RS232 Cable : Part Number 2403-0011 + + +e The appropriate HC Expansion Module, TTL/LIF-RS232. Part Number 2400-0068 + + +Vehicle Interface Box Installation Kit + + +Psion HC Cradle Technical Specification +Note: this HC accessory has been superseded by the Psion HC Docking Station. + + +Dimensions + +Size: 190mm (length) x 150mm (width) x 850mm (height) + +Weight: 400g + +HC compatibility Yes. Models prior to revision 4 (serial number below 200,000). +HC-DOS compatibility No + +Interfaces + +HC serial interface: High speed - 190kBytes/sec + + +Expansion module slot: Fits RS232/Parallel and Modem modules + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Battery recharge + + +Trickle charge: 14-16 hour recharge of HC battery in situ + +NiCad recharge slot: Allows charging of stand alone spare battery + +Features + +Security lock: Ensures HC held in position + +Insertion/removal: Trigger loaded spring release and hand recess + +Control panel: LEDs indicating mains power, fast charge, spare battery charge, active comms + + +Mounting options + + +Flat surface: e.g. point-of-sale counter +Wall mounting: e.g. industrial environments +In-vehicle: e.g. fleet vehicles + + +Psion's continuing product development and improvement programs mean that specifications and +features are subject to change at any time and without notice. + + +Psion HC Docking Station Technical Specification + + +Introduction + + +The HC Docking Station is designed to provide a multi-function mounting point for the Psion HC and +the Psion HC-DOS corporate hand held computers, (referred to in this technical specification as the +computer). + + +The Docking Station supersedes the HC Cradle, and has the following features: +e Battery management, including fast charge of batteries (fast model) +e Small footprint +e Reliable connection between the Psion and the docking station using the new LIF connector +¢ Option for in-vehicle use + + +e FCC, static and safety approval + + +Compatibility with Psion HC and RWAN machines +Compatibility with the Psion HC + + +To allow connection of the HC to the Docking Station using the LIF connector, the HC main circuit +board was revised so that the connections for the fast serial and charging interfaces were available at the +bottom expansion slot (version 4 onwards). As a result of this, Psion HC computers with pre revision 4 +boards (serial numbers below 200,000) are not compatible with the Docking Station or expansion +modules which have a LIF interface. The HC must also be reproed to version 1.70F or above of the +EPOC operating system. + + +A spares kit is available consisting of an HC main board (latest revision), plus the side and bottom +boards. This allows a field update so that early versions can be made compatible with the Docking +Station. Contact your Psion distributor for more information. + + +Only HC battery packs marked "Fast Rechargeable" and with the letters "FC" (for Fast Charge) in the +top right hand corner of the label are suitable for fast charging with the HC docking station. + + +Compatibility with RWAN/PDT220 +The Docking Station does not support RWAN/PDT220 machines. + + +Variants +A total of four build options available for the HC: +1. HC fast charge + + +HC PROGRAMMING GUIDE + + +2. HC trickle charge, +Note: Both the above variants are also available with vehicle support circuitry on board. + + +This gives a total of 4 possible build variants. + + +Identification + + +PCB number and revision marked on PCB is common for all variants. + +The main visual differences that distinguish an HC fast charger from a Workabout fast charger are: +HC fast charger: 4 pin bulky power supply socket fitted + +Workabout fast charger: 2 pin 1.3mm DC jack fitted + + +Docking Station Unit + +Main features + +The Docking Station Unit has the following features: +e = Fast charging of the computer internal battery pack, (fast model). +e Spare battery pack fast charging. +e Stable desktop mounting. + + +e Accepts some of the HC expansion modules which communicate via the Psion Fast Serial +(PFS) protocol. These are accessible by the HC and HC-DOS computers. See the table Psion +HC build variant and accessories matrix at the end of this Appendix for details. + + +e Data transfer from the computer, (with the appropriate expansion module and software driver). +e Simultaneous battery charging and data transfer, (if the Psion is not monitoring battery status). +e Wall mounting and bulk head fitting designed in. + + +e The battery compartment is factory configured to accept as standard the HC rechargeable +battery pack. + + +Status indicators +There are several LEDs on the front of the charger unit to indicate the following: +e¢ Communications/data transfer +e §=©Yellow during data transfer +e Power status-On/Off +¢ Green when charger is connected to mains power +e Main computer battery charging status (Fast model only, see Battery Status LED conditions) +e Spare battery charging status (Fast model only, see Battery Status LED conditions) +Battery charging +The Docking Station has two charging modes: +e = Normal + + +e Software controlled. See the Cradle and Docking Station chapter in the I/O Devices Reference +manual. + + +If both the computer and the spare battery are fitted when the docking station is connected to mains +power, charging priority will go to the spare battery. If the docking station is already connected to +mains power , charging priority will go to whichever battery was plugged in first. + + +The computer main battery can be discharged before charging commences. This feature is controlled +from the computer. + + +Note that the Slow Charge variant of the Docking station does not have a Battery Status LED. This is +because it has only one status - charging. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Battery Status LED conditions + + +LED indication Battery status + + +Flashing red Preparation for fast charging (two seconds) or +Battery condition outside specified range - trickle charging or + + +For the battery pack inside the Psion: discharging under software +control or + + +Error + + +Steady red Charging +Steady green Charged + + +Flashing red/green Waiting or + + +For the battery pack inside the Psion: discharging under software +control, while the spare is fast charging + + +Charging both battery packs + + +If a spare battery is inserted into the Docking Station whilst a battery pack inside the Psion is being +charged, charging of the spare pack will begin after the internal battery pack has been charged. + + +If a Psion computer is inserted into the Docking Station whilst a spare battery pack is being charged, +charging of the battery inside the Psion will begin after the spare pack has been charged. + + +If both the Psion and the spare battery pack are inserted into the Docking Station at the same time, (or +both are in the Docking Station prior to it being connected to the mains), the packs will not be charged +simultaneously. In the case of the Fast Charge variant of the Docking Station their respective LEDs will +flash red for about two seconds, until the charger decides which to battery pack to charge. The LED for +the one charging then comes on red, and the other one's LED starts flashing red/green as it is waiting +to be charged. For both Docking station variants the spare battery pack will normally be charged first. + + +Battery Fast Charging conditions + +The Fast Charge variant of the Docking Station can Fast Charge in the following conditions: +Within the temperature range: 5 to 45 °C + +Voltage of the battery pack: 4.5 to 11.3V DC for the HC and HC-DOS + + +If the battery pack temperature or voltage is outside the specified range, the charger trickle charges until +the condition is within the allowable range, after which it will fast charge. A new or fully discharged +battery pack (that has been left on for a long time) may have a voltage below the minimum for Fast +Charging. + + +If the battery temperature is within the allowable range and the battery status LED continues to flash +red it is likely that the battery pack is faulty. + + +Discharging prior to charging & capacity measurement + + +The Psion's internal battery pack may be discharged, under software control, prior to charging. This is +not possible with the spare battery pack. + + +It is possible to charge the spare battery pack whilst discharging the main battery pack in the Psion. + + +Software controlled discharging of the battery pack leaves the voltage above the allowable minimum for +subsequent Fast Charging. + + +Charging will automatically commence after the battery is discharged. + + +Under software control it is also possible to measure the actual capacity or the remaining capacity of the +battery pack inside the Psion computer. the discharging current for the HC is 300mA + 5%. + + +Fast Charging times + + +A fully discharged battery pack takes approximately one hour to Fast Charge to 90-95% of its maximum +capacity. If left in the Docking Station after this time it will be "topped-up" to its maximum capacity +after a further two hours. + + +HC PROGRAMMING GUIDE + + +Slow Charging times + + +A fully discharged battery pack takes approximately 14 to 16 hours to Slow Charge to 100% of its +maximum capacity. + + +Charging limitations + + +The Fast Charge and Slow Charge facilities only support the main Computer battery, not the battery of +any attached peripheral. The HC Printer however, contains its own Quick Charge circuitry and may +charge simultaneously under software control. + + +LIF Mounting Kit +The LIF mounting kit allows a LIF connector on the end of a cable to be fitted to a holster. + + +The holster itself is a plastic moulding into which the computer can be inserted. This incorporates a +positive latching mechanism which holds the computer securely in place. The holster does not include +any electronics. + + +The Clip cover and the 2 short screws that are fitted as standard to the LIF connector will need to be +replaced with the blank cover and the 2 long screws supplied with the kit. + + +HC/HC-DOS Holster with Socket Housing +The kit for the HC Computer consists of:- + + +e HC holster +e LiF connector rear housing +e LIF connector blank front cover + + +e 2screws - type K2.2 x 12 mm CSK ( not shown) + + +HC Docking Station + + +This is a Battery Charger with serial data communication capabilities supplied with a factory fitted + +HC holster, also known as an HC Docking Station. It comes in two variants, Fast Charge and + +Slow Charge. The cable from the hardware board to the LIF connector is protected by an over-moulded +rubber grommet. The HC Docking Station is also compatible with the HC-DOS computer. + + +A 12v 2 amp unregulated power supply is available separately. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +HC Docking Station: Part Numbers 1503-0017-01 (Fast Charge) +1503-0018-01 (Slow Charge) + + +12V 2 amp unregulated Power Supply + + +Note: Euro part number 2300-0212-01, US part number 2300-0213-01; a universal switch mode +adaptor is also available, part number 2402-0003-01 (contact your Psion distributor for details). + + +HC PROGRAMMING GUIDE + + +Psion LIF - RS232 Cable Technical Specification + + +A cable 1.5 m length terminated at one end with a LIF connector (Polarisation Type A) and a 15 way D +type (Male) plug at the other. LIF - RS232 Cable . + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Psion LIF Connector Technical Specification + + +The Low Insertion Force (LIF) connector has been designed for connecting the computer to the Docking +Station, as well as to other Psion accessories. + + +The LIF connector cover is moulded with a polarising pin in one of two positions. + + +Pin numbers + + +tot | GROUND 9 +2,3,4,5,8,10 +1,6,7,11 + + +2nd L_______} SIGNALS +3rd Cl] POWER + + +The step arrangement of the LIF Connector pins + + +Cable mounted LIF (Female plug) Computer mounted LIF (Male +socket) + + +Cable mounted LIF (Female plug) Computer mounted LIF +(Male socket) + + +The Type A and Type B polarisation of the LIF Connector + + +HC PROGRAMMING GUIDE + + +Pin Definition for LIF - PFS Connector +LIF Connector Polarisation Type B + + +Wire Colour Contact Direction Standard Function Docking Station usage +Gauge (Docking +Station's +perspective) +7/0.1 Brown Third Input Local! Computer Active. Used as an enable for +High when the computer is the Docking Station +on. (The Workabout can resident expansion +source 100mA from this pin module 5V supply. +and the HC/HC-DOS 5mA to +power remote* circuitry) + +EXON 7/0.1 Blue Second Output EXternal switch ON, active May be asserted by a +high (+5V). Asserted by a Docking Station resident +remote device to switch on expansion module. +the computer. + + +7/0.1 Orange Second Output INTerrupt to computer, May be asserted by a +active high (+5V). Docking Station resident +expansion module. +THM 7/0.1 Yellow Second Input Battery thermistor terminal. Standard function +Allows remote* sensing of +the battery temperature. + + +DLA 7/0.1 Green Second Output Disconnect Local? ASIC, Asserted by the Docking +active high (+5V). (does not Station ASIC, connects +apply to Workabout). When the Docking Station +this signal is asserted the resident expansion +serial channel is module to the serial +disconnected from the local? channel. + +ASIC4/5 in the HC resident +expansion module (if +present) and instead +connected to a remote +ASIC4/5 (if present). + + +BAT 28 Third Output +ve battery terminal (1 amp) Standard function +SWG +7 Vin 28 Black Third Output Power supply to computer Standard function +SWG (+10V) + + +SCLK 7/0.1 Serial channel CLocK. Standard function + + +White First Power, signal ground and - Standard function +ve battery terminal (1 amp) + + +SDATA | 7/0.1 Bi-directional | Serial channel DATA. Standard function + + +STATUS| = 7/0.1 Pink Third Output STATUS. Connected to a Driven low by an open +pull-up resistor to allow collector driver when +connection to an open- LCA is high and the +collector/drain driver. Normal Docking Station is +usage is: low indicates the powered-up to allow the +presence of a remote computer to sense +device. whether or not the + +Docking Station is +connected. + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +Pin Definition for LIF - RS232 Connector +LIF Connector Polarisation Type A + + +Wire Colour Contact Direction +Gauge (Computer's +perspective) +4 THERM | 7/0.1 eee ac Battery thermistor terminal + + +VBAT + + +cD + +RX + +TX +DTR + +me |] — + +VIN 8 +DSR + +ND +RTS +CTS + + +2 + + +D +G +7 Black Third Input Power supply to computer +G +G +G + + +2 +SW +2 +SW +2 + +Ww + + +peo fy cee +S) + + +10 + + +Definitions + +Computer HC, HC-DOS or Workabout + +Docking Station Expansion module fitted to the Docking Station, may or may not be present. +resident expansion + +module + +HC resident Expansion module fitted to the HC which contains the Docking Station interface + + +expansion module and possibly another peripheral. + + +HC peripheral A peripheral located in the HC resident expansion module which is connected to +the same serial channel as the Docking Station. + + +Docking Station An ASICS located on the main Docking Station PCB which remains connected +ASIC to the serial channel irrespective of the state of DLA. + + +Notes + + +1. The term "local computer" implies the computer local to the LIF connector, i.e. the HC, +HC-DOS or Workabout, as opposed to a "remote" computer which might be connected via a +Docking Station resident expansion module, for example. + + +2. The term "remote" implies something on the other side of the LIF connector to the computer. + + +3. The term "local" implies something on the computer side of the LIF connector including +devices on an HC resident expansion module. + + +HC PROGRAMMING GUIDE + + +Psion HC build variant and accessories matrix + + +KEY: @ Compatible X Not compatible / not available + + +HC | HC | HC HCR HC Workabout +y : 100 | 110 | 120 | 400/800 | Docking Docking +Build variants 900 Station | Station + + +alter peeled +a + + +se (ee [ca at ee + + +iii Galea a + + +a DE SG Hl Sa +SR +ps eee alee +SE +eee ee + + +HC Expansion modules + + +RS232 / Parallel (printer) version 1 not CE +1502-0001, 25 way D type (F) + 9 way Mini + +DIN + +FCC Class B, CE-mark, E-mark, EN60950 + +RS232 / Parallel (printer) version 2 + +1502-0052, 15 way High Density + 9 way D + +type (M) + +FCC Class B, CE-mark, E-mark, EN60950 + + +RS232 / TTL-RS232 +1502-0039 (IP64), 1502-0040 (NON IP64) +9 way D type (F) + 9 way D type (M) +FCC Class B, CE-mark, E-mark, EN60950 +e e e e e e + + +UK Modem (ASIC 8) 1502-0010 + + +RJ 11 connector + + +BABT Approved in UK, BS6301 (Safety) + + +APPENDIX A TECHNICAL SPECIFICATIONS + + +HC | HC | HC Workabout +: . 100 | 110 | 120 | 400/800 | Docking Docking +Build variants Station | Station + + +Barcode only + + +HP Wand HBCS-A207 + Plug + EXMOD +1502-0020 + + +Wand Welch Allen + Plug + EXMOD 1502- +0021 + + +FCC Class A / VDE Class B + + +RS232 / Barcode 1502-0044 + + +bG=Je] eGo +9 way D type Quick Loc(F) + 9 way D type (M) + + +FCC Class B, CE-mark, E-mark, EN60950 +MCR / Scanner / RS232 1502-0003 + + +MiniDIN connectors: +Scanner NipDenso + Plug (1502-0022) + + +Scanner DigVision + Plug (1502-0023) +Magnetic Card Reader + Plug (1502-0024) +FCC Class B / VDE Class B + +LIF-PFS / RS232 (available on request) + + +9 way D type (M) + 9 way LIF- PFS (M) +FCC Class B, CE-mark, E-mark, EN60950 + + +LIF-PFS / TTL-RS232 (due 1995) + + +9 way D type (F) + 9 way LIF- PFS (M) +FCC Class B, CE-mark, E-mark, EN60950 + + +LIF-PFS / Barcode 1502-0043 + +9 way D type Quick Loc(F) + 9 way LIF- PFS +(M) + +FCC Class B, CE-mark, E-mark, EN60950 + + +TTL-RS232 / LIF-RS232 (Vehicle) + + +9 way D type (F) + 9 way LIF- RS232 (M) +16550 RS232 / TTL-RS232 (1502-0045) +9 way D type (F) + 9 way D type (M) + + +FCC Class A + + +Fast Docking Station (Fast Charger with Holster) Peet Sapte +Charger Fast Charger without Holster (not yet available) al i a + + +Trickle Docking Station (Trickle Charger with Holster) e + + +HC PROGRAMMING GUIDE + + +HC Workabout +Docking Docking +Station Station + + +HC | HC | HC +; 2 100 | 110 | 120 | 400/800 +Build variants +Charger Trickle Charger without Holster (not yet xX +available) + + +Additional | Nicad battery pack 600 mA (1503-0005) Reise lea ae ae + + +accessories 15 way high density to 25 way Centronics +convertor cable (2403-0026) + + +APPENDIX B + + +SAFETY AND EMISSIONS APPROVALS + + +Safety and emissions technical terms explained + + +CE + + +EN60950 + + +EN55022 + + +FCC + + +TEC + + +IP + + +GS + + +From 1 January 1996 all electrical and electronic equipment, that fall within the +scope of 89/336/EEC (‘The EMC Directive’), sold in the EU must have a CE Mark. + + +The European Norm (i.e. a specification recognised throughout the EU) for Safety of +Information Technology Equipment. + + +The European Norm for Emissions from Information Technology Equipment. It is +known as a 'Product Specific Standard’. + + +Stands for Federal Communications Commission which is the body in the USA for +providing equipment authorisation. Class B are the emission limits the FCC have set +for residential equipment. Class A are the emission limits for commercial equipment. +Psion equipment for sale in the USA needs to meet the appropriate requirement. + + +Stands for the International Electrotechnical Commission which is a standards body +recognised by most western countries. IEC801 is known as a 'basic standard’ and is +divided into various parts, one of which covers static. The 801 series cover +susceptibility, or immunity. + + +Stands for International Protection. It gives a measure of how weatherproof a product +is. + + +Stands for Gepriifte Sicherheit ("Proof of safety"), which is used in Germany to +indicate safety. + + +INDEX + + +.btf files +HC, 3-1 +-mas files +HC ROM build, 5-1 +16550 RS232 /TTL RS232 module +specification HC, A-12 +application +keyboard restriction on HC, 2-9 +programs example HC, 2-4 +asynchronous +processing HC, 2-3 +asynchronous I/O +HC, 1-7 +asynchronous programs +HC, 3-2 +ATTRIBUTE +HC command, 3-7 +AUTO +HC command, 3-7 +BACKLIGHT +HC command, 3-8 +bar code interface +specification HC, A-17 +bar code reader module - version 2 +specification HC, A-15 +batch file processing +HC, 3-1 +BATCHK +HC command, 3-8 +BATTERY +HC command, 3-8 +CD +HC command, 3-9 +CE mark approvals +Europe, B-1 +Class B (FCC) +USA, B-1 +command +from remote PC HC, 3-3, 3-4 +command implementation +HC, 3-7 +command line editor +HC, 3-3 +command shell +copies of HC, 3-3 +HC, 3-1 +start up HC, 3-18 + + +terminating auto HC, 3-4 +terminating non auto HC, 3-4 +command syntax +HC, 3-7 +communication +with other computers HC, 1-13 +CONFIG +HC command, 3-9 +converter cable - 15 Way to 25 +specification HC, A-7 +COPY +HC command, 3-9 +copy protection +ROM customisation HC, 1-13 +cradle +HC, 1-3 +specification HC, A-20 +Cradle +connections hardware HC, 4-1 +connections software HC, 4-2 +HC introduction, 4-1 + + +port C HC, 4-1 +CRD: device + +driver HC, 4-5 +customising + +hardware HC, 1-10 + +HC, 1-10 + +software HC, 1-10 +D + +HC command, 3-10 +database + +support HC, 1-7 +DATE + +HC command, 3-10 +DELETE + +HC command, 3-10 +DEVICE + + +HC command, 3-10 +device drivers + +for HC, 2-9 +devices + +CRD: driver HC, 4-5 + +PMX: driver HC, 4-4 +DIR + +HC command, 3-11 +directories and files + +HC, 3-4 +display + +HC, 1-4 +docking cradle + +HC, 1-3 +docking station + +specification HC, A-21 +DOS + +not on HC, 1-14 +emast.exe + +HC ROM building utility, 5-1 + +utility program, 5-1 + + +HC PROGRAMMING GUIDE + + +EN55022 standard +Europe, B-1 +EN60950 standard +Europe, B-1 +ENV +HC command, 3-11 +environment variables +HC ROM, 5-6 +EPOC +explained HC, 1-6 +erom.exe +HC ROM building utility, 5-1 +HC ROM utility, 5-2 +utility program, 5-1, 5-2 +European +safety and emissions approval - technical +terms, B-1 +safety and emissions approvals, B-1 +European Norm, B-1 +EXIT +HC command, 3-11 +expansion modules +HC, 1-3 +FCC Class A standard +USA, B-1 +FCC Class B standard +USA, B-1 +Federal Communications Commission +USA, B-1 +file access +remote HC, 1-8 +file name +specifications HC, 3-6 +file names +command parameters HC, 3-5 +file paths +command parameters HC, 3-6 +files +in HC ROM, 5-3 +ROM based HC, 1-9 +files and directories +HC, 3-4 +files in use +error HC, 3-4 +FORMAT +HC command, 3-11 +FREE +HC command, 3-12 +gauge +example program HC, 2-5 +graphics calls example HC, 2-6 +graphics calls +gauge example HC, 2-6 +GS (Gepriifte Sicherheit) +German safety, B-1 +hardware +basic HC, 1-2 +customising HC, 1-10 +HC +.btf files, 3-1 + + +ii + + +application keyboard restrictions, 2-9 +asynchronous I/O, 1-7 +asynchronous processing, 2-3 +asynchronous programs, 3-2 + +batch file processing, 3-1 + +CLIB programming, 2-1 + +command implementation, 3-7 +command line editor, 3-3 + +command shell, 3-1 + +command shell copies of, 3-3 +command shell start up, 3-18 +command shell terminating auto, 3-4 +command shell terminating non auto, 3-4 +command syntax, 3-7 +communication with other computers, 1-13 +concept behind, 1-1 + +copy protection ROM customisation, 1-13 +cradle, 1-3 + +Cradle connections hardware, 4-1 +Cradle connections software, 4-2 +CRD: device driver, 4-5 +customising, 1-10 + +database support, 1-7 + +device drivers, 2-9 + +directories and files, 3-4 + +display, 1-4 + +EPOC explained, 1-6 + +example gauge program, 2-5 +example hello world program, 2-4 +example lined program, 2-6 +example programs, 2-4 + +expansion modules, 1-3 + +fast serial port, 1-3 + +file access remote, 1-8 + +file name command parameters, 3-5 +file name specifications, 3-6 + +file path command parameters, 3-6 +files and directories, 3-4 + +files in use error, 3-4 + +graphics calls gauge example, 2-6 +graphics window server, 1-6 +hardware basics, 1-2 + +hardware customising, 1-10 +hssram.sys configuring, 4-3 +introduction to, 1-1 + +keyboard, 1-5 + +Link connection high speed, 4-2 +lithium batteries caution, 1-4 +mastcpy, 1-12 + +master SSD, 1-12 + +memory internal, 1-2 + +multi-tasking, 1-6 + +not DOS, 1-14 + +path default, 3-5 + +pausing screen display, 3-3 + +PLIB explained, 1-6 + +PLIB programming, 2-1 + +PMX/HSS mechanism, 4-3 + +PMX: device details, 4-4 + +PMX: driver, 4-4 + + +power supply, 1-4 + +processor, 1-2 + +program launching, 3-1 + +programming choices, 2-1 + +programming for, 2-1 + +programming languages, 2-1 + +remote commands from PC, 3-3, 3-4 + +reprogramming, 1-11 + +reproing, 1-11 + +resetting, 1-11 + +ROM customisation, 1-12 + +romwrite, 1-12 + +screen, 1-4 + +shell process writing, 2-9 + +shell replacing, 1-10 + +software basic, 1-5 + +software customising, 1-10 + +software versions, 1-6 + +specification, A-3 + +SSDs, 1-2 + +switching on for first time, 1-1 + +synchronous processing, 2-3 + +synchronous programs, 3-2 + +terminating programs, 3-2 + +user interface programming, 2-2 + +window server buffer flushing, 2-6 +HC command + +ATTRIBUTE, 3-7 + +AUTO, 3-7 + +BACKLIGHT, 3-8 + +BATCHK, 3-8 + +BATTERY, 3-8 + +CD, 3-9 + +CONHIG, 3-9 + +COPY, 3-9 + +D, 3-10 + +DATE, 3-10 + +DELETE, 3-10 + +DEVICE, 3-10 + +DIR, 3-11 + +ENV, 3-11 + +EXIT, 3-11 + +FORMAT, 3-11 + +FREE, 3-12 + +KILL, 3-12 + +LDEV, 3-12 + +LINK, 3-13 + +LOWBAT, 3-13 + +LPROC, 3-14 + +LSEG, 3-14 + +MASTER, 3-15 + +MD, 3-15 + +NOTIFY, 3-15 + +OFFENABLE, 3-15 + +RD, 3-15 + +RENAME, 3-16 + +RESUME, 3-16 + +SET, 3-16 + +SETDATE, 3-16 + +SUSPEND, 3-17 + + +INDEX + + +TERMINATE, 3-17 +TYPE, 3-17 +VER, 3-17 +WAIT, 3-17 +WNOTIPFY, 3-18 +HC Cradle +introduction, 4-1 +specification, A-20 +HC docking station +specification, A-21 +HC modem (UK) +specification, A-18 +HC ROM +mas file, 5-1 +.mas file creating, 5-6 +-mas file required files, 5-7 +building utility emast.exe, 5-1 +building utility erom.exe, 5-1 +customisation options, 5-4 +customising, 5-1 +environment variables, 5-6 +files in, 5-3 +master file, 5-1 +master file creating, 5-6 +master file creation, 5-2 +master file requirde files, 5-7 +master SSD, 5-1 +mastering cautionary notes, 5-1 +size consideration, 5-4 +utility erom.exe, 5-2 +version numbers, 5-3 +hello world +example program HC, 2-4 +hssram.sys +configuring HC, 4-3 +IEC801 standard +International, B-1 +International Electrotechnical Commission +standards, B-1 +IP (International Protection +weather proofing), B-1 +keyboard +HC, 1-5 +restrictions on HC, 2-9 +KILL +HC command, 3-12 +launching programs +HC, 3-1 +LDEV +HC command, 3-12 +library services +ROM based HC, 1-9 +LIF - RS232 cable +specification HC, A-26 +LIF connector +specification HC, A-27 +lined +example program HC, 2-6 +Link +connection high speed HC, 4-2 + + +ill + + +HC PROGRAMMING GUIDE + + +LINK + +HC command, 3-13 +lithium batteries + +caution HC, 1-4 +LOWBAT + +HC command, 3-13 +LPROC + +HC command, 3-14 +LSEG + +HC command, 3-14 +mastcpy + +HC, 1-12 +MASTER + +HC command, 3-15 +master file + + +creating HC ROM, 5-2, 5-6 + +required files HC ROM, 5-7 +master SSD + +HC, 1-12 + +ROM HC, 5-1 + + +MCR /RS232 /TTL RS232 module - version 2 +specification HC, A-9 +MCR interface +specification HC, A-9 +MD +HC command, 3-15 +memory +internal HC, 1-2 +modem - HC (UK) +specification, A-18 +multi-tasking +HC, 1-6 +NOTIFY +HC command, 3-15 +OFFENABLE +HC command, 3-15 +parallel interface - 15 way high density +specification HC, A-7 +parallel Interface specification +HC, A-5 +path default +HC, 3-5 +pausing screen display +HC, 3-3 +PLIB +explained HC, 1-6 +PMX/HSS mechanism +HC, 4-3 +PMX: device +details HC, 4-4 +driver HC, 4-4 +port C +Cradle HC, 4-1 +power supply +HC, 1-4 +processor +HC, 1-2 +programming +choices for the HC, 2-1 +CLIB for the HC, 2-1 + + +iv + + +for the HC, 2-1 +languages for the HC, 2-1 +PLIB for the HC, 2-1 +programs +example gauge HC, 2-5 +example HC, 2-4 +example hello world HC, 2-4 +example lined HC, 2-6 +pseudo static RAM +PSRAM, A-2 +PSRAM +versus SRAM, A-2 +RD +HC command, 3-15 +remote file access +HC, 1-8 +RENAME +HC command, 3-16 +reprogramming +HC, 1-11 +reproing +HC, 1-11 +resetting +HC, 1-11 +RESUME +HC command, 3-16 +ROM +customisation HC, 1-12 +customisation options HC, 5-4 +customising HC, 5-1 +other components HC, 1-9 +ROM based +library services HC, 1-9 +romwrite +HC, 1-12 +RS232 / bar code reader module +specification HC, A-16 +RS232 / RS232 TTL interface +technical specification, A-9 +RS232 /TTL RS232 interface (9-way D-type) +specification HC, A-10 +RS232 /TTL RS232 module (16550) +specification HC, A-12 +RS232 interface +specification HC, A-11, A-13, A-16 +RS232 interface specification +HC, A-5, A-6 +RS232 TTL interface +specification HC, A-12, A-14 +RS232/Parallel (printer) module specification +version 2 HC, A-5 +RS232/Parallel (printer) module version 1 +specification HC, A-4 +safety and emissions approvals +Europe, B-1 +technical terms, B-1 +screen +HC, 1-4 +SDD +pseudo static RAM PSRAM, A-2 + + +PSRAM, A-2 + + +serial port + + +fast HC, 1-3 + + +SET + + +HC command, 3-16 + + +SETDATE + + +HC command, 3-16 + + +shell + + +replacing HC, 1-10 + + +shell process + + +writing for HC, 2-9 + + +software + + +basic HC, 1-5 +customising HC, 1-10 +versions HC, 1-6 + + +solid state disks + + +specifications, A-1 + + +specification technical + + +16550 RS232 /TTL RS232 module, A-12 +bar code interface HC, A-17 + +bar code reader module - version 2 HC, A-15 +converter cable - 15 Way to 25 Way HC, A-7 +docking station HC, A-21 + +HC, A-3 + +HC Cradle, A-20 + +LIF - RS232 cable HC, A-26 + +LIF connector HC, A-27 + +MCR /RS232 /TTL RS232 module - version 2 +HC, A-9 + +MCR interface HC, A-9 + +modem - HC (UK), A-18 + +parallel interface - 15 way high density HC, +A-7 + +parallel Interface HC, A-5 + +RS232 / bar code reader module HC, A-16 +RS232 / RS232 TTL interface, A-9 + +RS232 /TTL RS232 interface - version 2 HC, +A-10 + +RS232 interface, A-11 + +RS232 interface HC, A-5, A-6, A-13, A-16 +RS232 TTL interface, A-12 + +RS232 TTL interface HC, A-14 +RS232/Parallel (printer) module - version 1 +HC, A-4 + + +INDEX + + +RS232/Parallel (printer) module - version 2 + + +HC, A-5 + +solid state disks, A-1 + +SSDs, A-1 + +vehicle interface box HC, A-19 +SRAM + +versus PSRAM, A-2 +SSD + +specifications, A-1 +SSDs + +HC, 1-2 +SUSPEND + +HC command, 3-17 +switching on + +first time HC, 1-1 +synchronous + +processing HC, 2-3 +synchronous programs + +HC, 3-2 +TERMINATE + +HC command, 3-17 +terminating programs + +HC, 3-2 +TYPE + +HC command, 3-17 +user interface + +programming the HC, 2-2 +utility program + +emast.exe, 5-1 + +erom.exe, 5-1 +vehicle interface box + +specification HC, A-19 +VER + +HC command, 3-17 +version numbers + +HC ROM, 5-3 +WAIT + +HC command, 3-17 +window server + +buffer flushing HC, 2-6 + +graphics HC, 1-6 +WNOTIFY + +HC command, 3-18 + + diff --git a/docs/1-03 Series 3 3a Programming Guide 2.30_djvu.txt b/docs/1-03 Series 3 3a Programming Guide 2.30_djvu.txt new file mode 100755 index 0000000..3568216 --- /dev/null +++ b/docs/1-03 Series 3 3a Programming Guide 2.30_djvu.txt @@ -0,0 +1,5317 @@ +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 srscfile.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 +[<.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: + + + + + +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: + + +<0>[[]<0><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 +#include +#include + + +#include + + +#include + + +#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 +#include +#include + + +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 +#include +#include + + +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 (¬es1[0],&énotes2[0],len1l,len2,i,-1) +p_sleep (1); + +} + + +for (i = 0; i < 6; i++) +{ +play_notes (¬es1[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 + + diff --git a/docs/1-04 Workabout Programming Guide 2.30_djvu.txt b/docs/1-04 Workabout Programming Guide 2.30_djvu.txt new file mode 100755 index 0000000..1e82df9 --- /dev/null +++ b/docs/1-04 Workabout Programming Guide 2.30_djvu.txt @@ -0,0 +1,11144 @@ +SIBO 'C' Software Development Kit + + +WORKABOUT PROGRAMMING GUIDE + + +Version 2.30 + + +March 1, 1999 + + +(C) Copyright Psion PLC 1991-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 3a, 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 Introduction to the WorkaDout ...........scscccsccesccsrccesecesccesscssecssecsseeseesessseesesessesseseseesseseseseeees 1-1 +SWitChiti 9: On-atid OFF csc s5 ssecbessyss55sodutn duet cpan ca soonss des panda sucess ssc cuap hash ante dees pes dbsvecup sass 1-1 +Switching on for the first time... eee eeeeeeeneeesseecsneeceseecesaeeesseecsaeecseeseseeeesaeeesaeers 1-1 +StALtUp SSDs. vs cosessscteresies ahs vissasds ues cabs yateanaa ihe sedagues badass cobssaehsaasahecabstustssnesans sabetiss 1-2 + +The basic hard Wate: cesccccccseceicccsaccaeccdaceanccsvesanceaessancesevsercedescarcesvsdnecevsccencenvedsa ceneedeaceseadea 1-2 +IPLOGESSOM sa. vovasycustseedevetanteedoteveseds (ents beets lededss evils beetenedess Cotta beet deda tous beebevededagerss bushes 1-3 +Internal MeMOryscss.3 isha hesee ea yhetesiebeseentyheipetiadesycnetes vee deseenedals Sua deiyekaeaeeeeess 1-3 +Solid Statedisks (SSDS) sa. sss seesaheteck Geiss Ak cash aes ice Hen in cee Ghek Hk cae cee Heese aU dee 1-3 +Expansion modules <:.2:.2s:c.cneveiseut ens never sist vei ceavigussosh ues Saveeoabuanaes os aieees 1-3 +Communications’ POrts, .: siete. gedeasveg vest tefoceg ies bent ede vote seeghiet teseceiee paint dhteeeteuegeit aes 1-4 +"PE HOMSter sy cases seecevs gy feet ete beeen deh Sandee eee eaea a daee be ebudanoann edeedeeeddandaanedvvaeebidenieanedeebesy 1-4 +The Workabout Docking Station (Cradle) ............ccceccceeessceceeseeceeeeeneeeeeenneeeeeeneeeeeeeas 1-4 +POWer SUPPLY.ssasice ses sesetieasessie nite avd tht dia ev eaeead ies ey aaeeaE Vee Tne 1-4 +PRG TUS: «. sessthtees ectcede dart edenades Mes taseedeascatatedadeesdesaentadidetersdicnearadisedeaedieeectetedetiaedacbestathe 1-6 +Caution regarding lithium batteries 0.00.0... cee eeeeeeeeneeceneessneeceseeeesaeecsaeesseessneeeesaes 1-6 +DELEEI Fe sevchaticust ectewn vatetoansubest dev Ateteves tics den Selitle ces slive den alnveak tue stn talce sus biunetndaeneeeaveune gone 1-6 +Keyboard iccis scsi ites ccvescaeccstechaceeedcdaccvs ccaacevsdeaecesuccaa sen uccuaseauacaadeasdesacvsecesaevandeseevatcesediaa 1-7 +BUZZEi 2 ooccestitcatetevetans dc tcatetecstagece ecetutecstsench teal tude tatncnde cee tedstathsh Meath tucsscsuce tien siey 1-8 + +The: basic: Software vs. fos. de lbess eevsas eavdivs Avda tseaeback Atadees dactdaes Auge bead devded Suan hiae estigs Anatase. 1-8 +Versions of the Workabout software ............::cccssececeesseeeeeeenceeeeeeaeeeeeenneeesseneeeeesneeeees 1-8 +ROM. component scicc.sississsadecisssuecasnastasaapesadaastestgtaspesed subs oseageie sont susvanesessakd Maceohaaess 1-9 +Command: Processor s:ac..:ccscciesesciedessecnedestvahed csnvabedesushedontdenedensanhedenuehe dveaseheduvatenecee 1-9 +System Screen and PIM applications 20.0.0... eeeeeesecesseeesseessseeceseeeesaeecsaeesseeesseeeesaes 1-9 + +Resetting the Workabout ..........ccescceesscesseccesseeesseecscecscecsseecesaecesaeecsaeessaceseseesesaeeesaeeseaeess 1-10 +SOM TESCts aie. cori coors Se csctnk geet oe head a ath ecto od eh eteled aie teed AON tte 1-10 +Hard reset. cccses cess scavcessacat ceanceanceana cabevandevedeanacasesaa devedsanccaucues deveiaerccseccaacesvicaacesccaacees 1-10 +COld TESEt: ccesiee, cecditadsinattnessnt ated state voveintede delasids deiatelede lave degnintededadseteiadasebedadarevevacsteles 1-10 +What happens after a reset... eeeeeeseecssceceseeeesseeesseecsacecseecssaecessaeesseessteeesseeeesaes 1-10 + +Customising the Workabout ..............cccesscceceeenceeceeecceecesneeeeceeenaeeceseneeeeseaeeeeeeeaseeensnneeeenees 1-10 +Hardware Customisation ............cc:ccccessccceesenceeeeseceeeeeeeeecesnneeeecesseeeeeseaeeeeeeeneeesseeeeess 1-10 +Software CUStOMISATION ...........:cecccceessseeeeeseeeeeeeeeeeceseeceeeeseaeeeceseaeeeeeeneeeeeneeeeeeneneeees® 1-11 + +Connecting to other COMPULETS ......... eee eeeeeeseessseecsscecsseeceseecesaeeesaeecsaeecsaeecseesesaeeesatessaeers 1-11 +Hardware connection si.siss3.e.cccccsseicsvecueiessevendesvesendesesdardcenisenccseiderscovicanccesddendcnvcencens 1-11 +SOMWAre: CONMECHON 6.4. cecini Jes Aid cee cbs See RON oeeetid ses abcde eretnehes Glade dens abcteneteeeacts 1-11 + +2 Writing Software for the Workabout................ccssssscssssssccsssseccssscesssscsccsssscscesssscsesssscsesssnees 2-1 + +Basic programming ChOICES...........::ccceeeecceeeseceeceeneececeenceceeseaeeeceenneeeceeneeeeeseaeeeseeseeeeneaees 2-1 +Standard C (CLIB) or Psion C (PLIB) ou... cccccccssssccccccceesssssneeeeeeeeessesseeeeeeeeesseeaaee 2-1 +Writing the user interface ............ececcccceseccceeesneeeeeeeaeeceesnneeesseaeeeceenneeecseeeeeessaeeeesenees 2-2 +Synchronous or asynchronous Processing ..........:cseseccsseeceseeceseeesseeecseecsseeesseesesaeeesaes 2-2 + +CUStoMisatiOn OPtlONS ..........ccccccessncceeesececeeseeeecseeneeeeseeeeeeeeaeeceecesneeeeseeaeeeceenaeeesesneeeeenees 2-3 +Replacin® the: Startup Shell: ss os5-Mcissioie Asti esabiantie Anis aivien Aivisstees 2-3 +Replacing the Command Processot...........::ccscccsssccessseeesseeeeseeeesseecseessneecsseeeesaeeesaeers 2-4 +Replacing the System. Screen ...3..35..ccesesiasesadacseostesisseendoeseesteauaceebdaasoesteaesdeesdbadoeckedist 2-4 +Adding System Screen applications ..........c:cesscesssecsscecsseeeesseeesaeecseecseecesaeeesaeessaeers 2-4 +Supplying:an autoexec files.ci.ccsaeapiean liane ante Ane seis 2-5 + +Programming guidelines ............cceecccceessccceeeeeeceeseeeeceeseeeeeeeeeeeceesneeeeceeaeeeeeeeaeeeseenateeensas 2-6 +Some consequences of not running under the System Screen ...........ceeeeeeeeeeeeeeeeneees 2-6 +Data inte srity:.iice.vel ist aise. pai ste naval halos Hie ae ein bi ea ain ee! 2-6 +AGO-FIES ss oseedeertedederst cgeatsh ebedetabeteriastatedetepedesavtadigeter obicevatidete wba echadeeetabvnrectahe 2-7 + + +No access to WLD: or ALMS? .0......ccccccecccccesecccceecceceecceseeeececeuecceeseecceseueccsseuecseseeceees 2-7 + + +WORKABOUT PROGRAMMING GUIDE + + +Programming CxaMples...........seeeccesseesssecesseecsseecssceceseeeesseeesececsseecesseeesaeecsaeessneeseseeeenaes 2-8 +The: Vables:applyCation 's:. see. ecs sees teed ses oben ote tt dad avsk cee stetean sab env estedesh ant evened were 2-8 +The: Ledtestiapplicatt on .-.: ss.t.53 ocak civtaden us ioeks cobssah seul eoeieceh iota sguievesocebguhsqus eoubeavdgden ake 2-10 + +Workabout specific environment variables ............cccccccessceesseesseeeeeceeeeneeeeneeeseeeeseeenseeensaes 2-10 +SSSVER waccgesdescedaveeniatevt deviated etiveaeavaateiehiveedovia tea edneidivie bei badeaeienen ba deh elated 2-10 +CBP O recoshnten ote a ian settee a ead sai tee led Sah Ook eater ah Ok, Ren loet NA Des, Bon loet al ace, ad 2-10 +CSPA-t0:C$PZi,. env ckn elie ik neni ol bavi wan ev oval seed Wari eweineas oleae. 2-11 +CBRE ote ssena cede vetvDied tot atgateceDecbschasedateneDigvustasteatessdicbantecidstetelestevtedidadesaleva cetedidetetstisess 2-11 +COPS casccescosivscelecevcesnvdiveceeugeatuatohise cued i eaivdivedanvies vecabhavecaiubesndusdiss Gavtauecsaeseeneionees 2-11 + + +Error! Not a valid heading level in TOC entry on page 1 + + +Command Processor MENUS ...........sseceeseeesseeeesseessseecseecsseecesaeeesaeecsaeecseeseseesesaeeesaeers 3-1 +Font sizes and ZOOM SettingS ..........cscceeeeccesseeesseecsseeeeseseecseecscecsseeeesseecsaeesseeseneeensaes 3-2 +Batch file processing. 2) ssi s2s8s evts2exs sats Aiveceis ove sees Ave favs chvs cies Ake eehs evssoes Baa subacewscovs aes 3-3 +aun chin Programs: scssscsiiseaiasnsceuteanieendeseapesteansteasasesDeenegasteatsenapeatesustentaaaneeasaayse «ak 3-3 +Synchronous and asynchronous programs...........seceeecesseessseecsneeesseeeesaeeesaeesseeseeeenes 3-4 +Fermin atin ® Programs... iss oisssi asset Asveessaeeiesiaeteal Abvies Lao desiastisss Ancaster ts 3-4 +‘Phe command line: editor’ 2s. cogs is s2.5 saves cavscebaded Sines eevtckes eed stage sttevesiel siseesnieeved aaveeeed ss 3-5 +Pausing the screen: displays, ss.sissssciisgsviceetesissestdashoentactagectdsieeetectaaantdstenteteageetdanteess 3-6 +Running multiple System Interfaces ......... eee eeeeeeseeesseecsseeeeseecesaeecsaeecsaeessseeesseeeesaes 3-6 +Piles:and GireCtOries’ os ssncsedveeetiveg Sane vaup ouste cep set sens ousted ste sutgoent-cupsaseautpeautetey sams svtgeateaestes 3-6 +File In’ Use error Messages, 2..2..,5.0teciyieetuseie denise eegeede denies deeded aie dete denreesese 3-6 +Default path and current CirectOry .......... cc eeeeeeseccsseceseesseecseeceseeessaeecsaeessneeesneeeesaes 3-6 +Specifying file names as command parameters «0.0.0... ce seeeseeeeseeeeeeeceseeeseneeeseerseeeeee 3-7 +Specifying paths as command parameters ............esceesecceseeceseeeseeecsseecseeseseeeeseeeesaes 3-7 +Wildcards..:2i.shts neh heat Rite al aoe pe Bate ey he aeiee ess 3-8 +The requirements of generality... eee ee eeceeseecesneecseecscecessaeeesaeecsaeecsseessneeseseeeesaes 3-8 +Alphabetical listins.4-i.2cs4ccisascstiaictistativesilathcs sts hoeeuds bests Montistbaaatoatisseniaeetionss 3-8 +IN OFA EONS 325 5255s Shek sceh sul ak eons a biota end Seb vce oh Sachs oui Siuycanh ss chgeed Setecbebseehes Daesibcevscre bacnebehes 3-8 +Set or clear file attributes (ATTRIB)............:cccccccssssssecceccesssessneeeeeeeeessesseeeeeeeeeseeenaes 3-9 +Run the calculator application (CALC)... ceeeeseseecsseeseseeceseeeesaeecsaeesseeenseeeeseneers 3-9 +Call a batch file from inside another batch file (CALL)... ccccccccceccceeesessteeeeees 3-9 +Display or alter current directory (CD) ........eeeeeeseceseeesseecsseeceeeeeesaeessaeecseneeessaeeesaes 3-10 +Chanse:direct6ry (GHDIR)::. ei sisacaveere tiie antiess Landis nathan seohie nthe pds abitaa ds 3-10 +Clear the Screen: (CLS): fsce here ocre heise. da tested ential erential eed 3-10 +Run the communications application (COMMS) .........:ceseeesseeceseeeeereeeseessneeeeneeeesas 3-10 +Copy file(s) (CORY) 3 sins ili Bini Shien el ind ale liend etait 3-11 +Run the database application (DATA) ........eeeeeeceseeeeesneeesneeeseeceseeeesaeeesaeessaeessaeeeees 3-11 +Display:date (DATE) s2.cc5s.cceesecustie.duos caus eabvtied tubs falstberensh shin Padhosenss Ra Paes 3-12 +Delete: fle(S)i(DEUS) sxc c.sesissestishigestest cent astagesteaioraneuap eae siseentdeaapseuasloasigaasganaaicasiens 3-12 +Full directory: listing ‘(DER):3: si sk ud segs hess ion Sskeeeuheiieieeiecd ogchenshccebiued sans coubedeagesh oncnenwate 3-12 +Display message, set or display echo mode (ECHO) ..........eseessesseeceeneeseneeesneeeeeeeeee 3-13 +Run the program, script or batch file editor (EDIT) «0.00... eee eeeeeeseeeeseeeeseeeeseeeeeneees 3-13 +Delete: file(s) (ERASE) wce.scisissatashesadaasees na aiitcseaebentacinte pdaviasatassengaweesteaiateendaseastan 3-14 +Display error state (ERRLEVEL) .........eceeceesesseesseecsseeceseeessaeeesaeecsaeecsaeesseeeesaeeesaes 3-14 +Terminate the Command Processor (EXIT) .............ccccssscccecceeessessseeeeeeeseseessseeeeeeeeeees 3-14 +List:open' files: (RULES)... 2..scissetreuks fovdecbedeseescees hia devia ee bivnina cas A wetevs Ake fetta weeens eben 3-14 +Run a command for the files in a set (FOR) ...........cccccesscsssccecceesssesseeeeeeeeessssseeeeees 3-15 +Format and re-label local volume (FORMAT) ............cc:cccccccccessessseeeeeeeeessessseeeeeeeeenes 3-15 +Jump to label in batch file (GOTO)... cee ceeeeececessseeeessneeeceeeaeeeeesnneeesseneeeessneeeess 3-15 +List commands or get help (HELP)...........eeceesceeeseecsseeesseeeeseeeesaeecsaeesseessneessseeeesaes 3-15 +Run command conditionally (IF) ...........:cccccceesssceeeeeseeeceeeeeeceeneeeeeeeeeeeeeeaeeceeeneeeeeseas 3-16 +Kill a process (KILL) .0........eeccccceessceceessceceesneeeeeesaeeecesneeecseaeeecssnaeeceeceeeeeeeseaeeeeeeanees 3-16 +Add/alter disk volume label (LABEL) .............::cccccccsssssscceceeeessessneeeeeeeeessessneeeeeeeeeees 3-16 +Start Link progrart (IINK)) |issscies2.4s sess chee doetcavssibt Ans tout ca vesies Ale devs euereses das Pot eawsoevs devas 3-17 +List logical device drivers (LLDEV)..........:::::ccccsssscceeeeeeeeeeneeeesenneeeseeneeeeeseneeeesetnaaees 3-17 +List physical device drivers (LPDEV)..........:ssccesscessseecsseeceseseeesseecsaeecsaeessneeseseeeesaes 3-18 +List: processes’ (EPROG) oa ssi easievidssiiciecetesiascaassisens aosiesevabachacsansebecuvacevedsansinasusuebeaes 3-18 +List segments (SEG) 5c cecus tess tectes sci dav lieben suis Ses actve cenatvns fevialve bevseeee ies ivedeveteueds 3-19 +Make directory (MD), ici stsnscstcainecsslaiedetda weceatatedeteates castactedah athasstateastag nea lniedes 3-20 +Display free memory (MEM)............:ceesceeesecceseeeseeesseecsacecsseaeeesaeecsaeessaeessneeessaeeesaes 3-20 + + +INDEX + + +Make directory (MKDIR) .............ccecesccceeeenceeeesnceeeeeeneeeceseaeeeceeeeeeeseaeeeeeenaeeeseeneeeeeenee 3-20 +Suspend batch file processing (PAUSE )..........ceseesseessecsseeceseeessneecsaeecsaeesseesssaeeesaes 3-20 +Terminate current batch file (QUIT))..........ccccessscccccccesssesseceeeceeeesessseeeeeecesssesseeeeees 3-20 +Remove directory (RD)..........::ccscccecesscceceeseeeeceeneeeeeeeaeeeceenaceeeeeeeeeeseaeeeseeeaeeeseeneeeeeeeas 3-21 +Get the cause of the last system shutdown (REASON )............:cccsccceeesseeeeceeeeteeeeeenees 3-21 +Comment (remark) in batch file (REM).............cccccccccccesssesseeceeeeeessesseeeeeeeeessesseeeeees 3-21 +Rename file(s) (REN) ............cccccesssscceceessessnseceeeecesseesnsaeeeeceesesseseesaeeeeeceesessnsaeeeeeeeeess 3-22 +Remove directory (RMDIR)............cc:ccccesseceeeeseeeeeeeeeeecesnaeeeeseeeeeeseaeeeseenaeeeseeneeeeeeeas 3-22 +Display, set or delete environment variable (SET) ..........eeeeeseesseecsneeeeseeeeseeeeseeeesaee 3-22 +Alter system Settings (SETDEF) ccc csseesseeeeereesssesesesseseeees 3-23 +Run the spreadsheet application Sh3 (SHEET) ........ eee eeeeeesseeeeneeceneessceseseeseneeeesaes 3-24 +Shift batch file parameters (SHIPT).............:::cessssseceeeeeceeeeneeecesseeeceeneeeeeesneeeesseneeeees 3-24 +Start a process asynchronously (START)... eee eeeeeceesseeeceeseeesesseeeeceseeecesseeeess 3-25 +Stop,a process. (SWOP) ssc natalie ieatenietinner shies eit Noatesarhiel aes 3-25 +Display current time (PIME):0. 30005 so¢ ceusetestegssedekpsdessedg aces sctgedesseegunnd stp odeteedpstonectpens 3-25 +Type'a text file (TYPE) cccciseccavesseecevedsate cspdaetasvedaededeviaatedes donb cdevdsnadderdeioegevagabeaeebanties 3-26 +Display software version numbers (VER) ..........::essccessseesseesssceceseeeeseeeesaeesseesseeessaes 3-26 +Display the disk volume label etc (VOL) .........eeeeesceseseceeseetsseeceseeeesaeecsaeesseeesseeessaes 3-26 +Wait for a process to complete (WAIT) .0.... ee eee eeeseecsseeceseeeesseeesseecsaeessaeesseeeesaeeesaee 3-26 + + +Error! Not a valid heading level in TOC entry on page 1 + + +Psion Workabout Technical Specification ......... ce ceeseseseeceseeceseeeesseeesaeessaeecsseeseseeeeseaeers A-1 +Psion Workabout RS232 / RS232 TTL Interface Module - Technical Specification ......... A-3 +Psion Workabout RS232 / Barcode Interface Module - Technical Specification............... A-4 +Conversion of an HC barcode reader for Workabout COnNeCtiONn ...........:sseeeeeeeeeeeeeeee A-5 +Psion Workabout Vehicle Interface Cradle (VIC) - Technical Specification .................... A-5 +3 port and vehicle power OptiON............ecsesecessecsseeseeeceseeceseeeesaeecseesaeecseessneeseseeeesaes A-6 +1 port and vehicle power OptiONn............:::cccessccceeesteeeeeeeeeeeeeeeeeeseeeceseeecesnneeeeeeneeeeeeees A-7 +VIC Mounting: brackets: sc).ssisis: hese eesheihietae baile hisdead eid ciiibhiedediasues bidet A-8 +Vehicle:power 1nput:connectors; iss. stiee A siiessess arises thie oetinale arden asiis. estat A-8 +Conventional 9-pin RS232 serial POrts ...........eeeeeseeeesseeeeneeceneeseseeeesaeeesaeecseeseeeeses A-9 +Extended 15-way RS232 serial Port ...........cessccesecceseeeeeseecsseecseeesseeeesaeeesaeessaeesseeeeee A-9 +Psion ETP Connector.2i5..3 2aatied insist Bane cele ae ainidediee A-9 +Psion Workabout Docking Station - Technical Specification ...........eseeseeeeseeeeeeeeeneeeeneees A-10 +Introduction: 2c; aic ities iste ree ee vane teesaea A-10 +Vab amt ocean Mit OS et SN a dee eet ent lal eat a eee atone A-10 +Identification ssesiigev bel is Bee a orb ae ee i ae a) A-10 +Docking Station. Unit: .5.¢:h.scstece sce hecesedeeeeb ene esnsesues estersennpstelevesdcuboatyetheedbedesseshactpease A-10 +Maiti features: -ssscecysivecgistestecopeiyaese tiseeitesoyaees levies. Nenbaons diy belbehen yb mean Tee A-10 +StALUS ANGI CALOLS® «a fet S6es este bet Sheces catch eerie ses dated aacatec tact seh oul ont iasd ots osh uid ntentoet sen ate A-11 +Battery charging... c..sccccssecs ceevadaccsvceaes sat ccgeteandepecdacuvsccaa cus vecdasvauecdesaa devedsanccvescaa cevesees A-11 +Battery Status LED Conditions........... ce eeseesscsseeeeseessneecescecesaeeesecesatecsaeecsaeesseesesaeens A-11 +Charging both battery packs 0.00... ceeeeececeseeeesseeessecsaeecsscecssceceaecesaeesaeessaeessaeeseeeeses A-11 +Battery Fast Charging Conditions............:ccsesssccsseecsseeeeseeesecesceeesaeecsaeessseesesereeeene A-12 +Disharging prior to charging & capacity MeaSUFEMENt ........ eee eeteeeteeeeteeeeeeeeeeeee A-12 +Gar OTT SALES ies ess sce aces Me ede Do veses coteteets stebeded efupeans coyotes deg stetevess Mbsebovigetubewsoees cegerse A-12 +Charsing times! 3c...ysicatsiatiesesine aired stbe nett deste ee ibig dad derbaheeydeneieh A-12 +C@Bar srt elitr tat mi soso. Sse cae a ste Sect cans ols Satsc cone Shad okt ast stestnabuitennt Lestoreedteans A-12 +LIF Mounting Kat sess sccssveen cesccseecsnccdes seu ccgesenvccvecdactesccaa cevvecdaveaue vevaa devvesanccveiaescsbante A-12 +Workabout Holster with Socket Housing ...........seccsccesseccesseeesneecscecseecseecsseeeeseeeesaes A-12 +Workabout Docking Station ......... cee eeeeeeeseccseneeeseecseecsseecesaeeesaeecsaeecsneeeeseeeesaeessaeers A-13 +12V 1 amp unregulated Power Supply...........eeeeeeeeeccesseeesneecsneeceseeeesaeeesaeessaeeseeeeee A-13 + + +Appendix B - Differences between the HC Command Processor, the Workabout Command + + +Processor anid MS-DOS wsssssssccosscsssccscassccescadascencassccsocadaccesesssedennaca cad cacesssdsesenanacascssedsesenscnoassssceane B-1 +| ho A c076 11 (610 (010 Regeenaee oe Rt fenteate Brats tee tae BOE ee aN pT Rae ew at gee tee eat eI eee AE B-1 + +A DOut this appendix str csscieee cok abie ceviche eh wend see cu idl odevaued sevoeaans vesksenasebadse savkotncds B-1 + +He lip wiatsecdeccedvataeasaccatecdvavacccaa cose dgswa vatecaa cevedsvavetddan cuvedsa vece cane Peavara ee an cous sopvdgsniGbeseats B-1 + + +iii + + +WORKABOUT PROGRAMMING GUIDE + + +Commands: secscisciasisstecieastceasivadueseisatcesedsetecspicatccavdeatccuyiaad cenvieadussvacsecessatadeesviave ces B-1 +File and directory names.............cccccccesscceesenceeeeenceceeseaeeceeseneeesseeeeceeeaeeecsenneeeeseneeeseess B-2 +IWATACAT AS 555.5802 esc bette ot caceseuescareceaneis areeeea Sestewesnatnes se tavtaoensareerendaos eeuteornesestioneneseienens B-2 +Batch‘ files:::..2/.cscndacsstat Asset acie david acts saat neh Rattan anther eden B-2 +Default:directory Structure ss is.3 csvascceita shes eveadice nih acias cesiiwee sta ahve savas ceeiaa dresden dteeenies eee B-2 +Launching programse, :ssics.ccdaieseaccatcaiceateackecarsathc canoe canaanteessadengsusasuuecusaginesuaconaeecs B-2 +Memory resident programs ............sccessccceseeceseecsseecsseecsseecesseeesaeecseecseeseseeeesaeeesaeers B-3 +Alphabetical MH Stti os so: csc sees song stig gst neyo e8h soho vad ould, saebs caw ase enue otete led stot ecupscebenegedageeueacehetees B-3 +Append directories to current data path (APPEND; MS-DOS)...........:eeseeeseeeeseeeeee B-3 +Set or clear file attributes (ATTRIB { UTE})...........eececcccceeesncceeeseeeeeeeseeeeeseeeeeeeeees B-3 +Set time to auto-switch-off (AUTO; HC)............ccccccccccccssssssseceeeeeeeseessseeseeeeeeeeeeseesaaes B-4 +Set backlight time-out (BACKLIGHT; HC)............ececccceesscceeesneeeeeeseeeeceeneeeeeseneeeess B-4 +Backup files (BACKUP; MS-DOS) ...........cc:ccceeeesseceeseceeeeeeaeeeeeseneeecneneeeecssaeeeeesneeeess B-4 +Start battery check program (BATCHK; HO)..........:cesceeseessseeceseeeesseeeseesseeeeseeensaes B-4 +Specify battery type (BATTERY; HC) ..0.... eee eeeeseecssseecsseessseeceseeeesaeecsaeessaeeesseeensaes B-5 +Control extended CTRL-C checking (BREAK; MS-DOS) ............ccccceeesceeeeeteeeeeeeees B-5 +Run the calculator application (CALC)..........ceeessecceseecesneesseecscecsseeeeseesesaeesseseeeees B-5 +Call a batch file from inside another batch file (CALL) .............cccccccccccceesssstteeeeeeeeees B-5 +Display or alter current directory (CD) ........ eee ceesecesseeceseeeeseecseeceeeeesaeeesseessseeensaes B-6 +Display or change character set (CHCP; MS-DOS)..........eeeseeeseeeeseeeeseeeeseeeeseeeesaes B-6 +Display or alter current directory (CHDIR)............ceeccesssessseessseeceseeeesaeeesaeecseeenenaes B-6 +Check or fix disk (CHKDSK; MS-DOS )...........:cccccccccsssssceceeeceessesneeeeeeeessessseeeeeeeeeees B-7 +Prompt user for choice (CHOICE; MS-DOS )...........:c:cccecseseeeceeeneeeceeneeeeessneeeeeeeeeeess B-7 +Change directory (CUS), isc sciee det ots ps suc oes otek sith osteo tateses dcethdensiteh tee ath tntuebeebecbadegents exh B-7 +Start another command processor instance (COMMAND; MS-DOS) .............::::eee B-7 +Run the communications application (COMMS) ..........eeceeeseesseeceseecsseeeeseeeesaeeesaeers B-8 +Compare two files (COMP; MS-DOS)............ccccceessseceeeseeeeeseaeeecesnneeesseeeeeesnaeeeeseanees B-8 +Set language file (CONFIG; HC)... eeceesscssseecsseeeeseecesaeeesaeecsaeecseeesseeessaeessaeers B-8 +Copy file(s) (COPY )ssistcassdeatcesiecatccsedsatccsedsetecsudsetedevdeadedevicae ceescndedevdcdegdevecebeuenceds oes B-8 +Set country (COUNTRY; MS-DOS) .........eeeeeeecccceceeeesssneeeeeeecesessnnneeeeceeeeeeesnaneeeeeeeeees B-9 +Change terminal device (CTTY; MS-DOS) ...0.......cccccesescceessneeeceeeneeeeesnneeeeenneeesteaaees B-9 +Brief directory listing (D; HC)... eee eeeeeeseeesseeceneeceseeceseeeesaecesaeecsaeecseesseeesseeessaes B-9 +Run the database application (DATA) ..........ceeseeeseeceseeceseeeeseeeesaeeceaeessaeesseeesseeeesaes B-9 +Display date [and time] (DATE)..............::ccceesecceeseneeeceeneeeeeseaeeeceseneeecseaeeeeeeeaeeesseanees B-10 +Compress a disk (DBLSPACE; MS-DOS) ..0.......cccccecescceeesnececeeeneeeceeneeeeseeneeeeesneeeees B-10 +Start the debug program (DEBUG; MS-DOS) ......... eee eeseeeeseeceseeeesseeeseesseeeeneeeesaee B-11 +Optimise files on a disk (DEFRAG; MS-DOS) ...........:c::cccesesseceeeeeeeeeeneeeeeeeeeeeeenees B-11 +Delete file(S):(DEL[E TE), :.2 eess6et at, tatewesigit sae pass cottons Mite Gis on dat ee eat ees B-11 +Delete a directory, subdirectories and files (DELTREE; MS-DOS) .............: eee B-12 +List devices (DEVICE; HC).............::::ccccccssssssnsscccesesssnsnssseccesssssnsesseeeeesssensnsseeeeseeess B-12 +Full directory listing (DIR) ...........ccccceeseccceesenceeceeneeeeeseneeeceenaeeecesaeeeeessaeeecesneeeesseeeeess B-12 +Compare two floppy disks (DISKCOMP; MS-DOS) .........eesceseseeseseessseeeeseeeesneeseaeers B-13 +Copy a floppy disk (DISKCOPY; MS-DOS) ..........ceeeeseceseeceeseeceneecseeceseeeesaeeesaeers B-13 +Load/start DOSKEY program (DOSKEY; MS-DOS) ......... cc eeceeeseeeseeeeneeeeseeeeseeeesaes B-13 +Load DOSSHELL graphical interface (DOSSHELL; MS-DOS)...........eeeeeeeeeeeeeeeee B-13 +Display message, set or display echo mode (ECHO) ...........eeseeseessseecsseeeeseeeeseeeesaee B-14 +Run ‘file-editor (EDIT) 2k sesveccccsnthn asic. cen esos oas cadet as edaet eaeehe Seeds abot teevetives B-14 +Enable expanded memory (EMM386; MS-DOS)...........sccesseesseeceseeceseeceseeeesaeeesaeers B-14 +Display or set environment variable (ENV; HC)...........cceseceessecesseecsneeesneeseneeeeseeeesaee B-14 +Delete file(s)\(ERASE) prompt to indicate that its Command Processor is ready to receive commands, +and that the current drive is M: (internal). See the Workabout Command Processor chapter for +further details + + +e Selecting the System screen option starts the System Screen, displaying a set of icons that represent +the built-in example PIM applications. The description of the use of these applications is beyond the +scope of this manual. For information on how to create applications that run from the System Screen, +see the Programming the Workabout chapter (which relies on information contained in the +Series 3/3a Programming Guide). + + +e Selecting the Restart shell option runs the Startup Shell again. The machine then repeats the +sequence of operations described above. This is only of use if you want to run a customised Startup +Shell. + + +Startup SSD + + +A Startup SSD must contain a file with the file name autoexec. This may be a batch file, with a file name +extension of .btf, or it may be an executable program file with a file name extension of .img, .app, .opo or +.opa. If this is what is required, and you have a Startup SSD to hand, (it is not provided by Psion), insert +the Startup SSD and press Enter as instructed. + + +If you have copied an autoexec file to M: this will be run on startup, without displaying the startup +message described earlier. + + +The basic hardware + + +The Workabout is a member of the SIBO family of machines. This architecture is designed to minimise +the size, weight and power consumption of the computer. In relation to the Workabout, the key +components of the architecture are: + + +e A sophisticated power management system that selectively powers subsystems under software +control. + + +e Solid State Disks (SSDs) that provide fast low-power silicon-based mass storage with no moving +parts. + + +e Asynchronous serial interface for Psion peripherals running at high speed, and for +communications at 19,200 Baud. + + +e A 16 bit NEC V30H processor, (essentially compatible with 8086 class). + + +e Hardware protection of the system from aberrant processes (address trapping of out-of-range +writes and a watch-dog timer on interrupts being disabled). + + +e = Real-time clock. +e ROM-resident system software. +¢ Graphics LCD display. + + +See the Introduction chapter of the PLIB Reference manual for further information about SIBO computers +and the EPOC operating system that they all use. + + +All aspects of the hardware of the Workabout have been designed with the following goals in mind: +e Portability. +e Robustness. +e Splashproof. +e Data security. +e Ease of use. +e =©Adaptability. +e Long battery life. + + +e Standards compliance. + + +1 INTRODUCTION TO THE WORKABOUT + + +Processor + + +The Workabout uses an industry standard 80C86-compatible 16-bit processor, the NEC V30H, running at +a clock rate of 7.68MHz. + + +The Workabout also contains a number of proprietary custom chips called ASICs, which are responsible +for many of its more exclusive features. The principal ASIC chips are described in more detail in the +Hardware Reference manual. + + +Internal memory + + +The amount of internal RAM memory on a Workabout varies from model to model. There are two basic +models, with either 256KB or 1MB. + + +All models have 1MB internal masked ROM. +Solid state disks (SSDs) + + +The standard Workabout has two solid state disk drives, which are the equivalent of disk drives on a PC. +To access them, open the top cover by pressing down the catch to the left side of the Workabout's screen. +The drawer then slides out of the machine. SSDs can be inserted into the disk drives in the top right and +the bottom right of the drawer. + + +SSD/Battery drawer eject +button + + +SSD/Battery drawer + + +SSD in drive B: + + +SSD in drive A: + + +SSDs should be inserted with their upper faces (displaying large writing) uppermost. If you try to insert +them upside down, by accident, you will find they don't fit properly into their slots - so there is no risk of +any untoward damage, (unless you try to force them). + + +The SSD drive at the top of the Workabout drawer is drive A:, and that at the bottom is drive B:. +See the SIBO Computers Programmers Reference manual for further details regarding SSDs. + + +Expansion slots + + +There is an expansion slot inside the bottom end of the Workabout. This can contain a wide variety of +interface devices. Possibilities include: + +e RS232/RS232 TTL serial interface. + +e RS232/Barcode reader interface (for a wand or CCD/Laser scanner). + + +Sockets for the ports of these modules, (where fitted), are mounted as standard at the top end of the +machine, above the screen . One socket may optionally be located on the left of the bottom end of the +casing, below the keyboard. + + +These are factory fitted options, and it is not possible for the expansion module or port sockets to be +exchanged "in the field". Retro-fitting of expansion modules and sockets is possible, however. Contact +Psion for further details. + + +For further details of these modules refer to the Technical Specifications appendix of this manual. + + +WORKABOUT PROGRAMMERS REFERENCE + + +Communications ports + + +On the Workabout, the port names (e.g. TTY:A) depend on both the position that the port is located on +the machine and the way that the port is being used (e.g. RS232 or TTL): + + +Bouomneny—C | sd Cd +Tope [| SSC Cd CCS +[Bottom eRTopriaht [A | | |__| +Note: future hardware options may be available with different port assignments and positions. +The Holster + + +A plastic holster is available for storing the Workabout when it is not being used. It can be mounted on +any convenient vertical surface. + + +The holster incorporates positive latching to ensure that the Workabout is held reliably. A hand recess +guarantees easy insertion and removal. It may be mounted in any suitable position. + + +The Workabout Docking Station may also be fitted with the holster and the LIF Converter, (this +combination is also known as a cradle). + + +The Workabout Docking Station (Cradle) +The Psion Workabout Docking Station (Cradle) has been designed to satisfy requirements for: +e Secure mounting for the Workabout. +e "Hands-free" operation. +e Battery recharge. +e¢ Mounting an additional Psion HC type expansion module, such as a printer or modem. +The holster on the Workabout Docking Station (where fitted) is as described above. + + +A separate battery pack slot is provided to allow a stand-alone battery pack to be recharged. The +Workabout Docking Station also supports a fast recharge facility for the Workabout rechargeable battery +pack in the charger slot. + + +There is a LIF Converter on the Docking Station Cradle, for data exchange and external power to the + +Workabout. It is designed to be connected directly to a Workabout. The high reliability contacts of the +LIF connector automatically engage when the Workabout is placed in the Docking Station cradle - no +user-made connections are required. Alternatively an external power only LIF plug on a flying lead is +supplied with the holsterless version of the Docking Station. + + +Data may be exchanged at up to 19,200 Baud. +Power supply + + +The Workabout can be powered using a rechargeable nickel-cadmium battery pack, standard AA +batteries, or an optional mains adapter. + + +The Workabout will not switch on if there is no power source, or if the batteries are too low. Power is +needed to operate the Workabout and to maintain the data stored in internal memory. The storage of data +on SSDs, however, does not rely on the main power source. + + +Connect this end to + + +LIF converter Workabout LIF socket + + +3Link lead connector + + +At the bottom of the machine to the right, below the keyboard, is a socket for a LIF converter. To power +the Workabout from a mains supply, plug the cable from the mains adapter into the LIF converter and +then plug the LIF converter into this socket. The green power indicator light (near the Del key) will come +on. This light indicates that the Workabout is being powered by an external source - even if the +Workabout itself is not switched on. + + +1-4 + + +1 INTRODUCTION TO THE WORKABOUT + + +The Workabout is also supplied with a small round lithium battery. This is the backup battery. It is +essential because it keeps the internal memory secure in the absence of the main power source, for +example, while the main batteries are being changed. It should be fitted before the main batteries, but note +that the Workabout can not be run using only the backup battery. + + +To see where to fit the backup battery, release the drawer at the top of the Workabout by pressing down +the drawer eject button to the left of the screen (as for SSDs) until it clicks. Pull out the drawer to reveal +the backup battery cover in the top of the drawer, towards the left hand side. + + +The backup battery should last for approximately one year, provided the Workabout does not spend long +periods with no other power supply. It is recommended that a new backup battery is fitted yearly. If the +Workabout is left powered only by the backup battery, the battery will preserve the internal memory for +approximately five days. + + +To fit a new backup battery, slide back the backup battery cover and remove the old battery. Insert the new +battery so that the positive side of the battery faces left (towards the outer edge of the drawer). Slide back +the backup battery cover. + + +The main batteries are also stored in the drawer of the Workabout, next to the two SSD drives. The main +battery recess may contain a rechargeable battery cartridge pack. Do not attempt to disassemble a +rechargeable battery pack. + + +Main batteries + + +A new set of alkaline batteries should last for about 80 hours of continuous use. A fully recharged battery +pack should last for between 30 and 35 hours. Using the backlight (where fitted), or attached peripherals, +will increase power consumption considerably. If left unused, a battery pack will slowly lose its charge +over a period of approximately six months. + + +1-5 + + +WORKABOUT PROGRAMMERS REFERENCE + + +To remove the rechargeable battery pack or batteries, switch the machine off and release the drawer using +the drawer eject button to the left of the screen (as for the backup battery), pull the drawer out until the +main battery compartment is revealed, then push and lift any battery pack or AA batteries from the top of +the drawer. To fit the rechargeable battery pack or batteries back into the Workabout, slide into place, (left +end first). Ensure that good connections have been made between the battery terminals and the contacts +inside the battery recess, and close the drawer. The machine can now be switched on. + + +The nickel-cadmium batteries in the battery pack can be recharged in three ways: + +e Trickle recharge by a Workabout Mains Adaptor (via a LIF converter). + +e = Trickle recharge by a Workabout Docking Station. + +e Fast recharge by a Workabout Docking Station, provided they are "fast charge" batteries. +A second battery pack can be inserted in the Workabout Docking Station at the same time. + + +The Workabout automatically displays a warning message, when switched on, if either the main or +backup battery is low. Independently of this, there is a battery information dialog available from any +application. This is accessed by pressing the Shift-Ctrl-B key combination. It displays the state of the main +and backup batteries, and whether the batteries are alkaline or rechargeable, or whether an external power +supply is being used. For correct information ensure that the drawer is securely closed. + + +When the main battery is low, the Workabout may have enough power to display the screen and accept +input from the keyboard, but not enough to write to Flash SSD or access expansion devices. The +Workabout will turn off if an operation is attempted for which it does not have enough power. New +batteries should be fitted, (or the existing batteries recharged), before the operation is tried again. + + +In order to save power, the Workabout will, by default, switch itself off automatically, if left alone for five +minutes. The "auto-switch-off" time can be changed to another value, if desired, or the Workabout set so +that it does not auto-switch-off at all. + + +The fuse + + +The drawer of the Workabout contains a fuse (in the bottom of the battery compartment). This is to +generally protect the circuitry of the machine if too much current is being drawn through the batteries. If +the computer will not switch on, or has suddenly stopped working, it could be that a fault has caused the +fuse to blow. It may be possible to see the melted wire inside the fuse through its glass tube. If the fuse has +blown you should contact your Psion service centre. + + +Note that, if the fuse blows, the backup battery will still preserve the memory of the machine. Furthermore +the Workabout can still be powered from a mains adaptor via a LIF Converter. + + +Caution regarding lithium batteries + + +Note that there is a risk of explosion if lithium batteries are fitted incorrectly. Be sure that the backup +battery is fitted so that the face of the battery containing the plus symbol is the one towards the outer edge +of the machine. This is the flatter of the two faces. + + +A Lithium battery should be replaced only with one of the same or equivalent type as the one supplied by +Psion. Used lithium batteries should be disposed of according to the manufacturer's instructions. Always +tape over the terminals before disposal. + + +Screen + + +The normal Workabout screen is a retardation film LCD, 62.4mm (2.45 inches) wide by 30mm +(1.18 inches) high, displaying 240 pixels horizontally and 100 pixels vertically. The pixel dimensions +are 0.27mm by 0.23mm, with a pitch of 0.30mm by 0.26mm. + + +In the default (proportional) font, the screen displays seven lines, each with around 24 characters. If fewer +characters are required to be displayed, a larger font can be used, to achieve a more striking screen image, +(and vice versa). + + +Changing the font is only one example of the graphics support supplied by the resident software. + + +By default, the screen is illuminated by reflected light, using, (as throughout the Workabout), +state-of-the-art technology. In case additional lighting is required, some variants (e.g. the 1MKB variant) +are provided with a factory-fitted backlight. A backlight may also be retro-fitted to any model. This +backlight can be switched on or off whenever the user requires, (bearing in mind that there is an +inevitable additional drain on the batteries whenever the backlight is used). + + +1-6 + + +1 INTRODUCTION TO THE WORKABOUT + + +512K +RAM + + +VAOOEAGE + + +The switch for the backlight has a Sg symbol on it. In addition, the Workabout can be configured to +switch off the backlight automatically once a given time period has elapsed. + + +Screen contrast may be adjusted using the contrast key, which has a id symbol on it. Pressing this key on +its own makes the background darker. Pressing Shift-Contrast makes the screen background lighter. In +both cases the operation cycles round when the adjustment reaches the end of its range. + + +Keyboard + + +The keyboard features positive travel rubber keys with durable legends. + + +Two keyboard layouts are available, depending on how the Workabout is to be used: + + +e The standard full alphanumeric keyboard (57 keys). + + +e The alphanumeric keyboard can be augmented with special characters used in Scandinavian and +Western European countries. These characters can be printed on the key surround as a factory +fitted option, (above and to the right of the relevant keys). The extra characters are accessed via +the Psion modifier key once the "Special keyboard" has been selected. Note that the following +diagram shows these characters, but that they are not present on the key surround of a standard + + +machine. + + +@QX@ED,; + + +A) (6 MOGIG +QaHNOOWM +m) (N) 0) P) (@) @) +1G JOW +Ce) © © GBRGA +( y _) (crt) (aes) workabout + + +The following special keys are present: + + +On/Esc + + +Off + + +Menu + + +ce: (Backlight) Switches the backlight on and off, (where fitted). + + +Switches the Workabout off. + + +Switches the Workabout on, and functions as an Escape key, (used to clear a line of +input or cancel an entry). + + +The use of this is under application control, i.e. it is not used by any core system +code. It may be acted upon by the foreground process, or by any process that captures +the keypress including the Command Processor and System Screen. Used to bring up +a set of menus. In the Startup Shell it brings up the Special menu that allows you to +choose a system interface, or to restart the shell. + + +WORKABOUT PROGRAMMERS REFERENCE + + +d (Contrast) Controls the contrast of the LCD display. + + +Del + + +Enter + + +¥ (Psion) + + +Used to edit typing, and to delete items of various kinds, database records, for +example. + + +Terminates a line of input, exits a dialog, etc. + + +An extra modifier key (analogous to Alt on a PC), recognisable by its familiar "cup +and saucer" Psion logo. + + +There are also several special keypress combinations: + + +Shift-Esc + + +Ctrl-Esc + + +Psion-Tab + + +Psion-Space + + +Psion-Left +Psion-Right +Psion-Up +Psion-Down + + +Shift-Ctrl-B + + +Buzzer + + +The "Help" hotkey combination. The use of this is under application control, i.e. it is +not used by any core system code. It may be acted upon by the foreground process, or +by any process that captures the keypress including the Command Processor and +System Screen. It is used to bring up a Help menu. It appears to any application +exactly like the Help key on a Psion Series 3a. + + +The "Help index" hotkey combination. It is used to bring up a Help index. It appears +to any application exactly like the Ctrl-Help key combination on a Psion Series 3a. + + +The "Task" hotkey combination. It allows switching between tasks. + + +The "Caps lock" key combination. This is used to switch between normal and "Caps +lock" modes. In normal operations lower case characters are the default, with upper +case only when the Shift key is held down. In "Caps lock" mode, upper case +characters are the default and lower case characters are obtained by holding down the +Shift key. + + +The "Home" key combination. The use of this is under application control. + +The "End" key combination. The use of this is under application control. + +The "Page Up" key combination. The use of this is under application control. +The "Page Down" key combination. The use of this is under application control. + + +The "Battery" hotkey combination. It displays battery information: main battery state +and type, backup battery state and whether external power is present. It is available at +all times regardless of what application is running, (it is implemented in the Startup +Shell). Note: for correct information the drawer must be securely closed. + + +The Workabout contains a piezo buzzer for beeps, key clicks, etc. + + +The basic software + + +The software running on a Workabout at any one time is a mixture of: + + +e ROM resident core software (the "operating system"). + + +e ROM resident utilities, such as the MS-DOS like Command Processor, OPL program editor and +the LINK communications software. + + +e ROM resident PIM application software, (the System Screen, database, calculator, spreadsheet +and/or communications terminal emulator). + + +e Application software, from an SSD or internal memory. + + +e Library software, again from an SSD or internal memory. + + +Versions of the Workabout software + + +To see which version of ROM software is contained in any Workabout, enter ver at the > prompt in the +Command Processor. The Workabout ROM version number is given, plus a separate version number for +the EPOC operating system, and another one for the Workabout System Interface. + + +1-8 + + +1 INTRODUCTION TO THE WORKABOUT + + +ROM components + + +In addition to those files in the ROM that are common to all SIBO computers, there are several that are +unique (or specifically adapted) to the Workabout. These include: + + +sys$shll.img The Startup Shell, that displays the Psion logo when the machine is first +switched on, or after a reset. It runs any autoexec file, and gives the battery +information window. + + +sys$cmdp.img The Command Processor, as described in detail in a separate chapter. +sys$gsys.img The System Screen, as described in detail in a separate chapter. +sys$ctry.cfo This file holds all the language-dependent text strings used by the + + +operating system, as well as the standard keyboard layout information. It is +used in preference to sys$ctry.int when you select the Standard keyboard +option from the Command Processor's Control menu, or enter setdef /k0. + + +sys$ctry.int This file holds all the language-dependent text strings used by the +operating system, as well as the special keyboard layout information. It is +used in preference to sys$ctry.cfo when you select the Special keyboard +option from the Command Processor's Control menu, or enter setdef /k1. + + +opl.dyl Provides the facilities needed to enable programs written in OPL to be run. + + +oplts3.dyl Provides the facilities needed to enable Psion Series 3 type OPL programs +to be run on the Workabout. + + +The ROM also contains a number of built-in fonts (*,fon files). The Workabout fonts are identical to those +used in the Series 3a and are described in the Text fonts section of the Introduction chapter of the Window +Server Reference manual. + + +To obtain a listing of all the files in the ROM, enter dir rom:: at the > prompt of the Command +Processor. Note, however, that no file corresponding to EPOC itself appears in this listing. EPOC is the +kernel of the operating system, and not a file in rom: :. + + +Note: The ROM contains the file sys$soak.img. This is a soak test program that is intended for Psion use +only. Since this program erases everything in memory, it should not be run. + + +Command Processor + + +This application is included in the ROM for the benefit of program developers. It provides a DOS-like +command line interface. + + +In addition to the familiar DOS commands there are several commands peculiar to the Workabout. Some +provide information, such as usec. Others invoke features of the Workabout which are beyond the scope +of DOS, such as start which runs processes asynchronously. + + +This application can also run batch files. It is invoked transparently by the Startup Shell to run +autoexec. btf if required. + + +See the Workabout Command Processor chapter for further details. + + +System Screen and PIM applications + + +The System Screen application is included in the Workabout ROM as an example of a GUI application. It +is very similar to the Series 3a System Screen. + + +It provides much of the same functionality as the Command Processor, the major difference being that +there is no batch file handling. + + +Modified versions of the Series 3a personal information management (PIM) applications Data (database), +Calc (calculator) and Comms (communications), and of the Series 3 Sheet (spreadsheet) are included by +way of examples of the machine's potential. Most of the modifications concern the size of dialog boxes, in +that a smaller dialog box font is used when the applications run on a Workabout. + + +Details of the use of the System Screen and the PIM applications are beyond the scope of this SDK. An +introduction to their use may be found in the Workabout User Guide that is available with Workabout +machines. + + +1-9 + + +WORKABOUT PROGRAMMERS REFERENCE + + +Resetting the Workabout + + +It is rarely necessary to reset the Workabout. Even a serious bug in the application being developed is +unlikely to cause the entire Workabout system to hang. For example, any illegal attempt by an application +to write to data outside its own data segment will cause the operating system to terminate the application +in a so-called panic. The same thing happens if an application leaves interrupts disabled for too long. In +some instances of software failure, however, a reset may prove necessary. + + +To avoid the possibility of losing any data used by an application, terminate all applications and save any +important data to an SSD or a PC before performing a reset. + + +Note: There are two holes at the top and bottom centre of the keyboard on the Workabout. Neither of these +is for a recessed reset switch. + + +Soft reset + + +To perform a soft reset, press Psion-Ctrl-Del, (equivalent to Alt-Ctrl-Del on a PC, or pressing the reset +switch on a Psion HC or Series 3/3a). You will hear a short warning buzz. The Workabout then turns off, +abandoning all programs running at the time, without saving any data currently in use by them. The files +in the internal memory (M:) will not be lost, however. + + +Hard reset + + +If, unusually, all the internal memory (including environment variables) is to be erased too, keep the Shift +key held down while resetting the machine, i.e. press Psion-Shift-Ctrl-Del. You will hear a short warning +buzz. This is known as a hard reset. It is essentially equivalent to using: + + +e the reset switch on a PC + +e the reset switch with the ON/OFF key held down on a Psion HC + +e the reset switch with the ON/Esc key held down on a Series 3 + +e the reset switch with the right-hand Shift key held down on a Series 3a. + + +Cold reset + + +If neither a soft nor a hard reset work, remove all power and wait a few minutes before restoring power. +The machine must then be switched back on. You will hear a short warning buzz. This is called a cold +reset and will, like a hard reset, also erase the contents of all internal memory. + + +What happens after a reset + + +Following a hard or soft reset, or the temporary removal of all power, the Workabout displays the Psion +logo and startup message, as if switched on for the first time. + + +Customising the Workabout + + +This section describes some of the many ways a Workabout can be customised, to make it ideally suited to +some particular set of needs. + + +Hardware customisation +A backlight for the screen may be retro-fitted to any model if required. + + +Simple measures of hardware customisation include alterations to the labels and branding of the +Workabout, changes to the colour scheme and new keyboard legends. The machine may also be fitted +with a lockable battery/SSD drawer. More extensive hardware customisation, such as altering the +keyboard layout, are possible. + + +These measures of customisation are beyond the scope of this manual, which focuses instead on software +customisation. Contact your distributor if you wish to investigate the possibilities of hardware +customisation. + + +1-10 + + +1 INTRODUCTION TO THE WORKABOUT + + +Software customisation + + +The Workabout is designed to facilitate software customisation. Although (unlike the HC) the contents of +the ROM can not be reprogrammed, there are a number of ways in which the Workabout can run custom +application software. These include: + + +e supplying an autoexec file, + +e replacing the Startup Shell, + +e replacing the Command Processor, + +e replacing the System Screen, + +e adding further applications to those that run under the System Screen. + + +Only the first of these techniques is recommended as a standard way of customising a Workabout. +Nevertheless, the others are techniques that can be used if there is a particular reason for doing so. They +are described in the Programming the Workabout chapter. + + +Connecting to other computers + + +This section describes standard serial connections between a Workabout and another computer, such as a +PC or Apple Macintosh. The discussion is limited to describing connection to a PC, but similar +considerations apply to connecting with other types of computer. + + +Any connection between two computers involves a hardware connection and a software connection. +Hardware connection + + +Depending on the connectors fitted to the Workabout, a standard serial connection can be accomplished in +either of two ways: + + +e a standard serial cable connecting a Workabout RS232 socket (where fitted) to a serial port on +the other computer. + + +e a Psion 3Link serial cable connecting a Workabout, via a LIF converter, to a serial port on the +other computer. + + +Note: In order for the Workabout to recognise the presence or absence of the 3Link cable, the LIF +Converter must be disconnected from the Workabout before attaching or removing the cable. + + +Modern PCs have 9-pin sockets on serial ports; older ones have 25-pin sockets. It is common for PCs to +have two serial ports, designated COM1 and COM2. If you only have one serial port on your PC, it will be +COMI. + + +Some Psion communications software running on the PC recognises other serial port designations, such as +COMS3 or COM4. However, to ensure that communications will work in all cases, you should ideally +connect the PC end of the cable to COM1 or, if that port is not available, to COM2. + + +In either case the Workabout could be connected to the other computer via a modem and a suitable +telephone line connection. The Psion 3Link serial cable is supplied with all the necessary software, and +the accompanying documentation explains its use. + + +A Workabout connected to a modem may be used with the Psion 3Fax SSD software (but note that the +Workabout is not compatible with the Psion 3Fax modem). + + +Software connection +Communications software must be running on both machines that are connected via a serial cable. + + +The Workabout contains Link software that, in addition to allowing the transfer of serial data, provides +access to the filing system of the attached PC, provided that is also running suitable communications +software. The Link software can be started on the Workabout either by use of the Command Processor's +link command, or by selecting the Remote link option of the System Screen's Special menu. The Link +software is described in the NCP and Link chapter of the I/O Devices Reference manual. + + +The software on the PC should be Mclink, RCom (Remote Communications), or any other +communications software intended for communicating with a Psion computer. The Mclink software is +supplied with this SDK and is described in the Mclink, Mcprint and Slink chapter of the Additional +System Information manual. RCom (Remote Communications) software is supplied with the Psion 3Link +cable and is described in the accompanying documentation. + + +CHAPTER 2 + + +WRITING SOFTWARE FOR THE WORKABOUT + + +At the time of writing, either of two high level languages - C or OPL - may be used to develop application +software for the Workabout, although further languages are likely to appear in the future. + + +The use of OPL is described in the OPL Software Development Kit: this manual, not unnaturally, +concentrates on development in C. + + +Basic programming choices +Standard C (CLIB) or Psion C (PLIB) + + +As with all SIBO machines, a significant proportion of C code that has already written for other target +computers can be transferred almost straightaway to run on a Workabout. The availability of the CLIB +standard C library means that all that is required is to recompile and re-link the code. + + +To take a very simple example, the program simple.c +#include + + +int main (void) +{ +puts ("Hello world"); +getchar(); +return (0); + + +} +together with a project file simple.pr + + +#system epoc img +#model small jpi +#compile simple.c +#link simple + + +will run on a Workabout without any difficulty whatsoever (see the chapter Building an Application in the +General Programming Manual for further discussion of TopSpeed .pr project files and their usage). + + +However, it is recommended that Workabout developers rewrite the above program to use the Psion- +specific PLIB library, as follows: + + +#include +#include + + +int main (void) +{ +p_puts ("Hello world"); +p_getch (); +return (0); + + +} + + +WORKABOUT PROGRAMMERS REFERENCE + + +with the project file changed to: + + +#system epoc img +#set epocinit=iplib +#model small jpi +#compile simple.c +#link simple + + +The relative merits of CLIB and PLIB are described in the Building an Application chapter of the General +Programming Manual and the Introduction chapter of the PLIB Reference manual, and will not be further +discussed here. + + +Since the use of PLIB functions is essential for accessing many of the built-in software features - the +enhanced graphics facilities of the Window Server, for example - the remainder of this chapter is biased +towards PLIB. + + +Writing the user interface +A SIBO interface can be written in one of the following ways: + + +e Using console service functions such as p_printf, p_get1, and p_puts (or their CLIB +equivalents). These functions can only produce simple row and column text-based output, but can +be extremely useful when debugging an application. + + +e Using functions in the Window Server library with the contents of each window backed up with a +bitmap. This method is capable of producing a high quality graphical display, but can be +expensive in terms of memory usage. + + +e Using functions in the Window Server library with the contents of each window explicitly +redrawn. This method is also capable of creating a high quality graphical display. Furthermore, it +is more efficient than the use of bitmap backups, both in terms of memory usage and speed of +drawing. + + +If following either of the last two of these options, you have a further choice of approaches as follows: + + +¢ Make direct use of PLIB and Window Server library functions only. This approach gives you the +freedom to implement any form of user interface. However, development of any but a simple +interface may require a significantly increased programming effort compared with the following +two approaches. + + +¢ Combine PLIB and Window Server calls with the HWIF library. This approach to application +development, which uses standard C programming techniques, is described in the Programming +in Hwif manual. It provides access, with some restrictions, to the elements of the built-in user +interface that is used for the applications that run under the System Screen. + + +e Use object oriented programming techniques, combining PLIB and Window Server calls with use +of the built-in OLIB, FORM, HWIM and XADD libraries. This approach (referred to in this SDK +as HWIM programming) allows full access to the elements of the built-in user interface, at the +cost of an increased learning curve. See the Object Oriented Programming Guide for a +description of the relevant techniques. + + +These three approaches can, to some extent, be combined. It is, for example, permissible for programs +developed predominantly using either of the first two approaches to make object oriented accesses to the +OLIB library, which does not have any dependency on the choice of user interface. + + +Synchronous or asynchronous processing + + +There is a class of programs in which all input to a program comes via the keyboard. These programs can +be schematised as follows: + + +Initialise(); + +FOREVER +{ +ReadKeyFromKeyboard() ; +ProcessKey (); + + +} + + +Whilst waiting for a key from the keyboard, the program "hangs", i.e. it is unresponsive to other sources +of input. In this case the hanging of the program does not matter, as there are no other sources of input. + + +The call ReadkeyFromKeyboard makes what is known as a synchronous read for a key; it is synchronous +because it does not return until the keypress it is waiting for has been delivered: the return of the call +making the request is automatically synchronised with the delivery of the keypress. + + +2-2 + + +2 WRITING SOFTWARE FOR THE WORKABOUT + + +Consider another example of synchronous i/o. In this case, a program that is printing data might be +structured (at least in part) as follows: + + +Initialise(); + +FOREVER +{ +PrepareLineToPrint (); +SendLineToPrinter (); + + +} + + +This program loop terminates when there is nothing left to print. Now the process of sending a line of +data to the printer might take some time. Furthermore, the printer's buffer could be full, in which case the +program would have to wait for the buffer to empty a bit before being able to transmit the next line for +printing. If the call sendLineToPrinter is implemented synchronously, the program will "hang" in this +call until the data had been transmitted to the printer. In this state, the program is, again, unresponsive to +other sources of input. + + +A printing program could, and should, allow the user to terminate the printing while it is in progress by +simply pressing a predefined key. This means that the program must remain responsive to keypresses even +while data is waiting to be sent to the printer. Such a modification requires the synchronous call +SendLineToPrinter to become asynchronous. + + +The software on all SIBO machines has been explicitly designed to address these issues. For all but the +simplest of programs the concept of asynchronous events 1s central to successful programming on the +Workabout, and application developers are strongly urged to face up to this issue squarely, from the +beginning. Example programs in the Fundamental Programming Guidelines chapter of the General +Programming Manual cover the necessary concepts in a thorough yet straightforward manner. + + +Customisation options + + +The Workabout is designed to facilitate software customisation. Although (unlike the HC) the contents of +the ROM can not be reprogrammed, there are a number of ways in which the Workabout can run custom +application software. These include: + + +e replacing the Startup Shell, + +e replacing the Command Processor, + +e replacing the System Screen, + +e adding further applications to those that run under the System Screen, +e supplying an autoexec file. + + +Only the last of these techniques is recommended as a standard way of customising a Workabout. +Nevertheless, the others are techniques that can be used if there is a particular reason for doing so. + + +Replacing the Startup Shell + + +When the Workabout is first switched on (or following a reset), the Window Server sys$wsrv.img looks +for and runs a program called sys$shll.img. It looks for this program in the root directory of all local +drives, scanning them in alphabetical order, and finally in the ROM. Note that this is not the same search +order as is used to locate program files that are executed from the Command Processor. + + +The Window Server also looks for a program of this name, along the same path, whenever the Startup +Shell terminates - either normally or abnormally - so as never to leave the Workabout without a version of +sys$shil.img running on it. + + +The program started in this way is called the Startup Shell. The built-in version is the program that, on +start-up, looks for and runs any autoexec file or, if no such file is found, presents the Psion logo. + + +The Startup Shell program in the ROM can clearly be replaced by one on an SSD. There is, however, only +a very small RAM overhead involved in having the standard Workabout Startup Shell installed and, +unless an application needs as much available RAM as possible, there is little advantage in replacing it. It +may be of interest to note that this technique is, in fact, used by Psion during factory testing. + + +During development and initial testing, a replacement Startup Shell should be given another name, such +as workshil.img, and only renamed to sys$shll.img when you are sure that it is free of serious bugs. + + +2-3 + + +WORKABOUT PROGRAMMERS REFERENCE + + +If a replacement Startup Shell is on an SSD, you can revert to the built-in version simply by removing the +SSD and performing a soft reset. This will preserve any data in the machine's RAM. With a replacement +startup shell on the M: internal drive, the only way to revert to the built-in Startup Shell is to perform a +hard reset, or to remove all power from the machine - including the backup battery. This will also erase +any other data held in RAM. + + +Replacing the Command Processor + + +The ROM Command Processor is provided for development work, supporting a rich variety of file +management, task management, system configuration, and batch file processing commands. However, this +functionality brings its own cost in RAM consumption that may well be undesirable for a Workabout +running application software. For this reason the Command Processor is not loaded into RAM when the +Workabout is first switched on. + + +The Startup Shell on the Workabout, sys$shll.img, looks for a program called sys$cmdp.img if the +Command processor menu option is selected from the System Interface selection dialog, or if the +Command Processor needs to be loaded to execute a batch file. In either case it looks for the file in + +the root directory and then the \img directory of drive A:, and then in each of the other local drives +(including M:). The drives are scanned in alphabetical order. If the file is not found in any local drive, the +search concludes by looking in the ROM. The Command Processor program in the ROM can thus be +over-ridden by one in any local drive. (Note that the search order is not the same as that used to locate +program files that are executed from the Command Processor.) + + +If a replacement Command Processor is on an SSD, you can revert to the built-in version simply by +removing the SSD at a time when the Command Processor is not running. If the replacement is on the M: +internal drive, reverting to the built-in version may be less easy. If the replacement Command Processor +allows you to exit, you can do so and then rename or delete it from, say, the System Screen. Otherwise, the +only option may be to perform a hard reset. + + +One possible use of a custom Command Processor file is to discourage "hackers". Minimal custom System +Interfaces could be provided on the same SSD as the autoexec file, and could even be copied automatically +onto the internal drive. These custom System Interfaces would merely notify the user that their chosen +option was not allowed and return them to their application program or to the Startup Shell. + + +Replacing the System Screen + + +The built-in System Screen and the applications that run under it are provided mainly to illustrate some of +the possibilities for custom applications, but they may also be useful for development work. + + +The Startup Shell on the Workabout, sys$shil.img, looks for a program called sys$gsys.img if the System +screen menu option is selected from the System Interface selection dialog. It looks for the file in the root +directory and then the \img directory of drive A:, and then in each of the other local drives (including M:). +The drives are scanned in alphabetical order. If the file is not found in any local drive, the search +concludes by looking in the ROM. The System Screen program in the ROM can thus be over-ridden by +one in any local drive. (Note that the search order is not the same as that used to locate program files that +are executed from the Command Processor.) + + +If a replacement System Screen is on an SSD, you can revert to the built-in version simply by removing +the SSD at a time when the System Screen is not running. If the replacement is on the M: internal drive, +reverting to the built-in version may be less easy. If the replacement System Screen allows you to exit, you +can do so and then rename or delete it from, say, the Command Processor. Otherwise, the only option may +be to perform a hard reset. + + +As with the Command Processor, one possible use of a custom System Screen file is to discourage +"hackers". Minimal custom System Interfaces could be provided on the same SSD as the autoexec file, +and could even be copied automatically onto the internal drive. These custom System Interfaces would +merely notify the user that their chosen option was not allowed and return them to their application +program or to the Startup Shell. + + +Adding System Screen applications + + +Strictly speaking, this technique should not be termed customisation, but is included for the sake of +completeness. + + +It is not a viable option for the vast majority of end-user machines, but can be a useful aid to development +work. The following types of file, copied to any local drive, can be run under the System Screen: + + +¢ application programs, written in C, with a .app extension and located in a \app directory (directly +installable from the Install option of the System Screen's Apps menu) + + +2 WRITING SOFTWARE FOR THE WORKABOUT + + +e image files, written in C, with a .img extension and located in a \img directory (run from the +RunImg icon that can be installed by means of the Install standard option of the System Screen's +Apps menu) + + +e translated OPL applications, with a .opa extension and located in a \opa directory (directly +installable from the Install option of the System Screen's Apps menu) + + +e translated OPL programs, with a .opo extension and located in a \opo directory (run from the +RunOpl icon that can be installed by means of the Install standard option of the System Screen's +Apps menu) + + +Any such program written for the Series 3 will run without modification on the Workabout. + + +In principle, Series 3a programs should also run on the Workabout. In practice, Series 3a programs may +need some degree of modification to ensure, for example, that any dialogs and command menus will fit on +the Workabout's screen. + + +See the Series 3/3a Programming Guide for information on writing applications to run under the System +Screen. + + +Supplying an autoexec file + + +Most end-user machines will run customised application software via the built-in autoexec mechanism, by +which the Startup Shell will search for and run a file with the file name autoexec and an extension that is +one of: .img, .app, .opo, .opa, or .btf. + + +The Startup Shell first searches for a file with the name autoexec.img in the root directory and then in a +\img subdirectory of drive A: The search for this file continues in all other local drives, taken in alphabetic +order, that is, in B:, C: (if it is present) and M:. The Startup Shell does not look for autoexec.img in the +ROM. + + +If such a file is not found, the Startup Shell searches for other autoexec files in the following order: +¢ an autoexec.app file in the root directory and a \app subdirectory +e an autoexec.opo file in the root directory and a \opo subdirectory +e an autoexec.opa file in the root directory and a \app subdirectory +e an autoexec. btf file in the root directory and a \bff subdirectory +In each case all local drives are searched in alphabetic order, as described for the search for autoexec.img. + + +If an autoexec file is written in OPL (that is, it has an extension of either .opo or .opa) its execution +requires the OPL runtime software provided by the file sys$prgo.img. The search for this file looks in the +root and \img directories of all local drives (again in alphabetic order) and finally in the ROM. This +search order allows the built-in sys$prgo.img to be replaced, if required. + + +If the autoexec file is a batch file (that is, with extension .btf) the Startup Shell will need to locate and run +the Command Processor, whose file name is sys$cmdp.img, to interpret the batch file. The search for this +file looks in the root and \img directories of all local drives (again in alphabetic order) and finally in the +ROM. This search order allows the built-in sys$cmdp.img to be replaced, if required. + + +No command line parameters are passed to any autoexec file that is run by means of this mechanism. In +practice, many .app or .img application programs may require command line data, such as the name of a +data file to open. In such a case, the solution is to use a short autoexec. btf batch file that starts the main +application program, passing it such command line data as may be needed. + + +A further use for such an auxiliary autoexec batch file is to provide a convenient way to make any +necessary alterations to the default machine settings before running an application. The following +example batch file autoexec. btf illustrates both of these uses: + + +REM Set 24 hour clock and Summer Time ON + +SETDEF /t24 /ts+ + +REM Run the MY_APP.IMG program, passing two command line parameters +START my_app my_file my_param + + +Note that the program is started asynchronously, by means of the start command. The advantage of +doing this is that execution of the batch file continues to its termination once the program has been +started. On termination of the batch file, the Command Processor will automatically be unloaded, thereby +releasing as much memory as possible for use by the main program. + + +2-5 + + +WORKABOUT PROGRAMMERS REFERENCE + + +An autoexec. btf batch file must not require any intervention from the user. It must not, for example, +contain any pAusE commands. Any other command that may require confirmation from the user, such as +DEL, must be used in the form (e.g. pzEL /y) that requires no such confirmation. + + +See the Workabout Command Processor chapter for further information about writing batch files and +using Command Processor commands. + + +Programming guidelines + + +Because of the close similarity between their operating systems and the built-in software libraries, +programming for the Workabout is very similar to programming for the Series 3 and Series 3a. The +information in this section concentrates largely on the more significant differences. Although of interest to +all Workabout developers, some of the topics will be of particular significance to those who are already +familiar with developing applications for the Series 3 and/or Series 3a. + + +As has been mentioned earlier, programs written for the Series 3 or the Series 3a can, in principle, be run +without modification on the Workabout, whether they are written using CLIB, PLIB, the HWIF library or +the HWIM object oriented user interface. In practice, Series 3a programs may need some modification +because of the smaller screen size on the Workabout. In HWIF or HWIM programs, menu bars, pull-down +menus and dialogs may all need to be reorganised to occupy less space. Note, however, that the +Workabout permits dialogs to be displayed in a small font (this is supported for both HWIF and HWIM +programming) and this may eliminate the need to otherwise modify the dialog contents. + + +One further point that may cause unexpected behaviour in an application transferred from, say, the +Series 3 is the presence of additional keys, such as the Backlight key, on the Workabout keyboard. It is +worth a careful check of the list of special keys, given in the Events chapter of the Window Server +Reference manual, for differences in the various keypresses that are passed to an application running on +different machines. + + +Some consequences of not running under the System Screen + + +All application software on the Series 3 and Series 3a is run from the System Screen (see the Series 3/3a +Programming Guide) whereas on the Workabout it is not. With the possible exception of software used +during the development process, Workabout application software is normally run by means of the +autoexec mechanism, either directly or via an autoexec.btf batch file, as described earlier in this chapter. +In this respect, programming for the Workabout has much in common with programming for the HC (but +with the additional possibilities arising from the availability of grey when writing to the display and of the +graphical user interface services provided by the built-in object libraries). + + +Workabout applications that do not run under the System Screen have no need for the icon and shell data +files that are built into each Series 3/3a application (usually with a .app extension) that can be directly +installed under the System Screen. These files contain information specifically for the use of the System +Screen, when installing and launching the application. See the Add-files section later in this chapter for +more information on the files that may be built into a Workabout application. + + +Applications that are not run under the System Screen obviously will not receive System Screen messages. +One of the uses of such messages is to inform a Series 3/3a file-based application, while it is running, to +open or create a different file. By default on the Workabout, information about which file to use can only +be passed on start-up of the application, in the command line. + + +In an HWIM application, command line processing is provided by the am_init method of the application's +instance of (a subclass of) pwrmman. This processing is based on the assumption that the data in the +command line is of the form supplied by the System Screen - as described in the Series 3/3a Programming +Guide. If the application uses a different format for command line data, it will have to supply its own code +to process that data. As for all applications running under EPOC, the command line data - with a leading +count byte - is pointed to by the magic static DatcommandPtr. + + +Data integrity + + +Compared with those written for some other SIBO machines, a Workabout application is likely to be more +critically dependent on access to data, stored either in RAM or in files. + + +2 WRITING SOFTWARE FOR THE WORKABOUT + + +Failure to access or to write data because the battery is too exhausted is likely to be disastrous if the user is +away from a source of replacement power source. To some extent, this problem can be avoided by +establishing a policy of regular battery replacement. In addition, the system software performs battery +status checks each time the machine is switched on and will give the appropriate warning message if +either the main or backup batteries need replacing. + + +In some cases it may, however, be worth considering building regular battery status checks into the +application software and giving the user application-specific warnings. Comprehensive information on +battery status can be found by use of the PLIB functions, such as p_supply and p_supplyinfo, that are +described in the Power supply section of the General System Services chapter of the PLIB Reference +manual. + + +Another potential source of problems is if a user opens the drawer, say, to change an SSD or to replace the +batteries, and does not subsequently close it. In such a case, not only is the data on the SSDs inaccessible, +but the Workabout is then susceptible to the ingress of dirt and moisture. If such a situation is possible, +and is of concern, the application should make explicit checks at appropriate intervals. + + +It is not possible to check for an open drawer by means of a call to the PLIB function p_iocchg, since +EPOC only registers the change that is reported by this function at the time that the drawer is +subsequently closed. Suitable methods of detecting an open drawer would be to attempt to access an SSD +file that is known to exist, or to call p_dinfo for drives A: and/or B:. + + +Add-files + + +Any executable that is built to run on the Workabout may have up to four additional files, known as +add-files, embedded within it. These files are combined with the main file by emake.exe, at the time the +.img file is created. The inclusion of these files is controlled by the presence or absence of an add-file list +(.afl) file with the same name as the .img file that is being created. See the Building an Application +chapter in the General Programming Manual for further general information about add-files. + + +The add-file list (aff) file is a plain text file, containing a list of up to four files that are to be embedded in +the executable. An application that is to run under the system screen will generally have three embedded +files: an icon, a resource file and a shell data file. Consider, for example, such an application, named +myapp.app (by convention, a .img file containing add-files is renamed to have a .app extension). An +appropriate add-file list file would be named myapp.afl and could have the following content: + + +myapp.pic +myapp.rsc +myapp.shd + + +The first and last of these three files are used by the System Screen when installing and running the +application. In Series 3 and Series 3a applications, the icon may also be displayed in an application's +status window, but the Workabout status window, however, never displays an application's icon. For +further details of the icon and shell data files, see the Series 3/3a Programming Guide. + + +In principle, the four possible add-files may be used for any application-specific purpose. An application +for the Workabout will, in general, not be run from the System Screen and will therefore not need to +contain embedded icon and shell data files. The application may, however, need to use a resource file and, +although not mandatory, it is recommended that this file be embedded in the application. + + +If the application contains an embedded resource file, and if the resource file is accessed via the OLIB +RSCFILE Class, then the resource file must be embedded as the second add-file. This will almost certainly +be the case for any application developed with the aid of the HWIM library. Such an application must +have a resource file and will normally take advantage of the option for the pwrmman application manager +automatically to create an instance of rscFr1ue. If there is no need for any other embedded files, a dummy +file, preferably of zero length, must be created and included as the first embedded file, to ensure that the +resource file occupies the second slot. + + +No access to WLD: or ALM: + + +The services required by the wip: device driver are supplied by the World application that is built into the +Series 3 and Series 3a ROMs, but is not present on the Workabout. + + +Similarly, it is the Time application on the Series 3 and Series 3a that provides the services required by +the atm: device driver. Again, this application is not supplied on the Workabout. + + +In consequence, any application using either of these device drivers will fail if run on the Workabout. + + +WORKABOUT PROGRAMMERS REFERENCE + + +Programming examples + + +The vast majority of the examples that are supplied with this SDK are suitable for use on the Workabout. +The Console examples (that is, those that use only the simple PLIB I/O functions for writing to the screen) +are largely machine-independent and will run without modification. Most of the example applications that +use either the HWIF or HWIM libraries will also run on the Workabout, unless they depend on, say, the +wider screen of the Series 3a, or make use of facilities (such as the Series 3a's additional sound services) +that are not available on the Workabout. + + +The \sibosdk\wkdemo directory that can be installed from the Optional disk contains two examples, one +written using HWIF and the other being an object oriented HWIM application. + + +The Tables application + + +The HWIF example is a modified version of the Tables program that is described in the Worked Examples +in Hwif chapter of the Programming in Hwif manual. The unmodified version of Tables will, of course, +run on the Workabout in compatibility mode, using a 240 x 80 region, centred vertically. + + +Amongst other things, the Workabout version illustrates the modest number of changes that are, in +general, necessary to convert a 'standard' Hwif application into one that is customised for running on the +Workabout. Since the Tables program is described in some detail in the Programming in Hwif manual, +the description here will concentrate on the changes that have been made. + + +Apart from the project file, tables.pr, the entire source of the Workabout version of the application is +contained in the single file tables.c. The application does not use a resource file and, if it is not run from +the System Screen, it needs neither an icon (.pic) file nor a shell data (.shd) file. The Workabout version +therefore does not need the tables.afl add-file list, nor any of the files that it lists. Note that, in the original +HWIF version, the file tables.rsc is a zero-length dummy file, whose sole purpose is to ensure that +tables.shd is added in the third add-files slot. + + +The first modification is to switch out of Series 3 compatibility mode by setting the value of the variable +_UseFullScreen to a non-zero value: + + +GLREF_D UWORD _UseFullScreen; + + +GLDEF_C VOID main(VOID) +{ +_UseFullScreen=TRUE; +uCommontInit (); +SpecificInit(); +MainLoop () ; +} + + +In consequence, the application will occupy all 100 lines of the screen and the height of the main window, +IN ReduceScreenSize, is changed from 80 to 100 pixels. Note that the use of a status window is +maintained. This avoids changing the width of the window, which would otherwise introduce a large +number of trivial changes to the code in terms of the horizontal positioning of the window contents. The +status window on the Workabout does not show an application's icon, even if one is built into the +application. When first started, the application has the appearance as shown below. + + +COE D Syren) +Node +C4) (3) Ce) ©) +iJ G@) GIG) +o) CE) Ca) Gem) +A) CB) (©) () (CE) C) +S) + + +CN ©) (P) (a) (A) +uo fe SS A +TM OW) OW) CO +(a NY) REN +Cs) CO @) SBIGH + + +ye Ctrl) (pace) workabout + + +2 WRITING SOFTWARE FOR THE WORKABOUT + + +The vertical positioning of all the window's content is adjusted, not only because of the increased height of +the window, but also because by default the Workabout uses an 11 point font (with font ID +WS_FONT_BASE+9) whereas an 8 point font (with font ID ws_ront_Basg) is used when running in Series 3 +compatibility mode. The larger font is also needed when creating the edit box, in createEditor, that is +used to receive the answer, as illustrated below. + + +Score: 6 correct out of 6 +Testing all tables +(up to 12 times 12) + + +The code to create all but one of the dialogs of the original HWIF version remains unchanged, although +their appearance changes since they make use of grey in the dialog border. The following illustration +shows the Limits dialog. + + +Score: 1 correct out of 1 + + +Limits for testing + + +‘ +‘Highest table. 12 \j4u) EX +| 11:44 + + +Wed 25 + + +The dialog presented by selecting the Mode option, which selects whether to present tests on a particular +multiplication table, or on all tables, is just too wide to be displayed in the normal font. This dialog is +therefore set to use a smaller font: + + +GLREF_D UWORD _SmallFontDialog; + + +LOCAL_C VOID ChangeMode (VOID) +{ +H_DI_CHOICE ch; +INT 3; +TEXT buf [20]; + + +_SmallFontDialog=TRUE; + + +if (uOpenDialog ("Mode") ) +return; + + +The resulting appearance of the dialog is as follows: + + +Score: 1 correct out of 1 +Testing all tables + + +The application can be built in the normal way, by typing: +make tables + + +The easiest way of running it is to copy tables.img into a \img directory on the Workabout and then, from +the Workabout's Command processor, typing: + + +tables + + +WORKABOUT PROGRAMMERS REFERENCE + + +The Lcdtest application + + +The Lcdtest example is an HWIM application, using the object oriented techniques that are described in +the Object Oriented Programming Guide. + + +The application was written to test drawing to the Workabout's screen. It displays a variety of patterns, +occupying every pixel. When first started, the application presents the display shown below. + + +HHHHHHHHHHHHHHHHHHHHHHHHHHHH +HHHHHHHHHHHHHHHHHHHHHHHHHHHH + + +The numeric keys, from 1 to 6 inclusive, switch to alternative display patterns, and pressing the 0 key +inverts the current display pattern. + + +The application has a small menu bar, with Control and Special menus. The Special menu offers an Exit +option and the Control menu has options to test the backlight (assuming that it is fitted) and to test sound + + +output. +mummers) Control_|_Special_) cesses +Backlight ~B +Sound S| NN + + +The dialog presented by selecting the Sound option is shown below. + + +CDEFGHI JKLMNOPQRS TUUWXY ZABCDEF +GHI JKLMNOP@QRS TUVWXY ZABCDEFGHI J + + +|___Make test sound _/PPOR +bl Duration (ticks) Abe +‘Pitch(512/kHz) 3208 pcp +=FGH +I JKLMNOPQRS TUVWXY ZABCDEFGHIJKL +MNOP@GRS TUUNXY ZABCDEFGHI JKLMNOP + + +The Ledtest application is built by typing: +make lcdtest + + +Note that, since this application has a resource file that is read by means of an instance of the OLIB +RSCFILE Class, the resource file is built into the application, in the second add-file slot. This requires an +add-file list, Icdtest.afl, to be supplied, with contents: + + +dummy .pic +lcdtest.rzc + + +The file dummy.pic is of zero length, and is used to ensure that the (Huffman compressed) resource file is +built into the second add-file slot. + + +Workabout specific environment variables +The following environment variables are used only on Workabout machines. + + +S$SVER + + +Contains a text string representing the Workabout System Screen version number, for example, “1.00F’. + + +C$P@ + + +This environment variable is set when exiting from the Workabout command processor. It contains a +single ASCII character representing the current drive, with a default value of ‘M’. + + +2-10 + + +2 WRITING SOFTWARE FOR THE WORKABOUT + + +C$PA to C$PZ + + +The environment variable cspa may be set when exiting from the Workabout command processor, to +contain a text string representing the current path on drive A. It is not set if the drive A path is to the root +directory. + + +Similar environment variables may be set for all other possible drives - csps to cspz inclusive. + + +C$P£ + + +This environment variable contains the parameters used by Link when accessed from the Workabout +System Screen and/or Command Processor. + + +C$P$ + + +This environment variable is set following selection of the keyboard from the Command Processor or the +System Screen. It contains a single byte whose binary value is either 0 (Standard keyboard selected) or | +(Special keyboard selected). + + +2-11 + + +CHAPTER 3 + + +THE WORKABOUT COMMAND PROCESSOR + + +The Workabout Command Processor System Interface is started by selecting the "Command processor" +option from the Startup Shell's command menu. + + +Commands can then be entered by typing at the Command Processor, in response to a > prompt. Instead of +commands being entered one at a time, batch files can be invoked, to run a series of commands +consecutively - or simply to cut down on typing. For example, typing: + + +xbat + + +is shorthand for invoking all the commands stored in the file xbat.btf. Note that batch files must have the +extension of .bff. + + +The Workabout Command Processor provides an DOS-like utility for functions that can be executed from +a command line. In addition to the familiar DOS commands there are several commands peculiar to the +Workabout. Some provide information, such as LsEc, which lists the memory segments used by a process. +Others invoke features of the Workabout which are beyond the scope of DOS, such as start, which runs +processes asynchronously. The range of functionality covered includes file and SSD management, program +management, information requests, and Workabout configuration. + + +Although use of the Workabout Command Processor is similar to the way you would use the DOS +command line, there are several important differences. For example: + + +e Relative paths, such as ..\*.*, are not supported and the * wildcard in a file name is handled in +a slightly different way from the way it is handled in DOS. + + +e =In the Workabout Command Processor, environment variable names are case-sensitive. In +addition, the content of an environment variable is not restricted to text, and may include binary +data. + + +The differences are explained in the later sections of this chapter. +Two features are available in the Workabout Command Processor, but not in the DOS command line. + + +e Asmall set of menu options can be accessed by pressing the Menu key. These are described in the +Command Processor menus section of this chapter. + + +e At the command line prompt, pressing Shift-Esc brings up a Help menu; pressing Ctrl-Shift-Esc +brings up a Help index. + + +Command Processor menus + + +If the Menu key is pressed at any time when using the Workabout Command Processor, then a menu bar +with three menus is presented. The options in these menus are mainly concerned with setting parameters +and states that have a global effect. For the default machine settings, see the ss TDEF command in the +Alphabetical listing section, later in this chapter. + + +Each menu option may be accessed using an accelerator key combination that is shown in the menu, +adjacent to the corresponding option. The available options and their corresponding accelerators are listed +below. + + +WORKABOUT PROGRAMMERS REFERENCE + + +Time menu +Time and date [Psion-T] Set the system time and date, (see Formats) +Summer time [Shift-Psion-S] | Set summer time On or Off +Formats [Psion-F] Set date to be displayed in one of three formats: + + +Day month year +Year month day +Month day year + + +Set the date separator to any non-alphanumeric character. +Set the time format to either am-pm or 24 hour. +Set the time separator to any non-alphanumeric character. + + +Set the "start of week" day to any day of the week from +Monday to Sunday. The default is Monday. + + +Control menu +Sound [Psion-S] Set all sounds to be On or Off. +Set beeps to be Loud, Quiet or Off. +Set keyclicks to be Loud, Quiet or Off. + + +Auto switch off [Psion-A] Set auto switch off of the machine to Yes or No or "If no +external power". + + +Set the auto switch off time of the machine to any whole +number of minutes between one and thirty. + + +Set auto switch off of the backlight to Yes or No. + + +Set the auto switch off time of the backlight to any whole +number of minutes between one and ten. + + +Set the backlight key as Disabled or Enabled. + + +Special keyboard [Psion-K] Switch between "Special keyboard selected" and "Standard +keyboard selected". There is no dialog. + + +Special menu +Remote link [Psion-L] Set remote link On or Off + + +Set the baud rate to one of 300, 600,1200, 2400, 4800, 9600 or +19200. + + +Set the communications port to A, B or C. +Set any extra parameters required. + + +Wrap on [Psion-W] Switch between "Wrap is on" and "Wrap is off". When Wrap +is on, displayed text does not disappear off the edge of the +screen, but continues on the next line. There is no dialog. + + +Zoom in [Psion-Z] Increase the character font size. +Zoom out [Shift-Psion- Decrease the character font size. +Z| +Exit [Psion-X] Return to the Startup Shell (Psion logo) + + +Font sizes and zoom settings + + +The Workabout can display characters in many fonts. The command Processor uses five different font +sizes. The use of Zoom in and Zoom out increases or decreases font size, (see above). Zooming in (from a +larger to a smaller font) will re-display some of the information that scrolls off the top of the screen in a +larger font size. + + +3 WORKABOUT COMMAND PROCESSOR + + +The five different zoom settings give the following number of characters per line and lines of text on the +screen: + + +Font size Number of — Characters +lines per line +6 12 39 +8 9 29 +11 7 27 +13 6 23 +16 5 18 + + +Batch file processing + + +Batch files are plain text files, containing a sequence of Command Processor commands, each on a +separate line. By default, EPOC batch files have extension .btf. They are normally expected to be stored in +a \btf directory. + + +To invoke the batch file with name backup. btf, just type backup at the > prompt in the Command +Processor. Batch files are always run synchronously. This means that while the batch file is executing, the +user cannot task back to the Command Processor and continue to issue other commands. No additional +commands can be typed into the Command Processor until any batch files it is executing have completed. + + +If necessary, the full path of the batch file should be given too. Thus: +loc::b:\batch\backup + +or +rem::c:\workabt\devp\restore.bat + + +The extension needs to be supplied only in cases where it differs from .btf: Note that Joc:: specifies the +local filing system (the default) and rem:: specifies the remote filing system. + + +If the batch file name is preceded by start (see Launching programs below) it will still be run +synchronously; thus: + + +start loc::b:\batch\backup +is exactly the same as: +loc::b:\batch\backup +Batch files can also call other batch files, and so on, up to eight levels deep. +If more complex functionality is required, a program should be written, to replace the batch file. + + +Launching programs + + +As well as running batch files, the Command Processor can be used to launch programs - either EPOC +executables (typically with extension .img or .app) OPL programs (with extension .opo) or OPL +applications (with extension .opa). + + +Like batch files, these other programs are run simply by typing their name. +Typing the line + +dojob +has in fact the following effect: + + +e The Command Processor checks for an internal command with the name tinx. If such a +command is found, it is executed. + + +e If no such command exists, the Command Processor looks for a file dojob.img in the ROM, and +then in a \img directory on each of the local drives. If such a file is found it is executed. + + +e If no such .img file exists, the Command Processor looks for a file dojob.app in the ROM, and +then in a \app directory on each of the local drives. If such a file is found it is executed. + + +WORKABOUT PROGRAMMERS REFERENCE + + +e If no such .app file exists, the Command Processor looks for a file dojob.opo in the ROM, and +then in a \opo directory on each of the local drives. If such a file is found it is executed. + + +e Ifno such .opo file exists, the Command Processor looks for a file dojob.opa in the ROM, and +then in a \app directory on each of the local drives. If such a file is found it is executed. + + +e If no such .opa file exists, the Command Processor looks for a file dojob.btf in the ROM, and +then in a \b¢f directory on each of the local drives. If such a file is found it is executed. + + +In all cases, the local drives are searched in the order A:, B:, C:, M:. + + +Note that, for example, a file dojob.img will be found in preference to a file dojob.btf. To ensure that a file +with a specific extension is run, enter the extension explicitly, for example: + + +dojob.btf + + +A program may be run from a directory other than the standard directory for a file of that type, provided +the directory is specified explicitly, for example: + + +\mydir\dojob.img + + +will execute the first dojob.img file that is found in a \mydir\ directory in one of the local drives (the drives +are searched in the same order as is given above). + + +In general, any drive, path and/or extension that is included in the command will confine the search +appropriately. + + +Additional command line parameters can be passed to a program. For example, +dojob.app b: +will execute dojob.app, passing it a command line containing the string "b:". + + +Synchronous and asynchronous programs + + +In contrast to batch files, which are always run synchronously (see above), programs can be run either +synchronously or, exploiting the multi-tasking capabilities of the Workabout, asynchronously. + + +By default, a program is launched synchronously, if its name is entered on its own. This means that while +the program is executing, the user cannot task back to the Command Processor and continue to issue other +commands. + + +To run a program asynchronously, prefix the program name with the keyword start. This means that +while the program is executing, the user can task back to the Command Processor and continue to issue +other commands. + + +When the program is started, it will by default (assuming that it has some form of user interface) take over +the foreground screen. To access the Command Processor, or indeed any other tasks that may be running +on the Workabout at the time, press Psion-Tab, ("Switch task"), as many times as is required. Every time +Psion-Tab is pressed, a different program cycles into foreground. + + +Note that there is no need to quit the foreground program in order to start another - start a new program +by pressing the Psion-Tab key combination until you get into the Command Processor, then type the name +of the program at the command line, (with or without the preceding start, as required). + + +However, users should avoid starting up new programs unnecessarily - since each additional program +reduces the processing time, memory and other resources available for the programs already running. + + +Terminating programs + + +Many programs contain mechanisms within themselves for the user to terminate them. For example, they +may contain an Exit command. + + +Alternatively, programs can be killed from the Command Processor, using either the stop or KILL +commands. As is explained in the alphabetical listing below, stop should be used in preference to KILL +whenever possible. The relevant menu options should be used to stop the built-in Psion applications. + + +Note that if a program is run synchronously, it is not possible to terminate it by tasking to the Command +Processor that launched it - since that Command Processor is inaccessible until the program terminates. + + +The Psion-Shift-Ctrl-K keypress combination kills the current foreground process. In extreme +circumstances, recourse to resetting the Workabout may be required. + + +3-4 + + +3 WORKABOUT COMMAND PROCESSOR + + +When a program launched from the Command Processor terminates, either normally or abnormally, the +Startup Shell reports this fact to the user. + + +The command line editor + + +Up to 32 previous commands can be reviewed by means of the Up and Down cursor keys at the command +line. Any previous command displayed in this way can be edited before being issued again. + + +To clear the command line at any time, press Esc. + + +As would be expected, each individual command is entered to the Workabout by pressing Enter after +typing its name. The command name can never be abbreviated. The names of the built-in commands and +their parameters are not case sensitive. Parameters to user-developed applications. however, may be case +sensitive. + + +Certain other keys and key combinations also have special effects in the command line editor, (or when a +batch file is running). + + +Enter Terminates a line of input. + +Del Del on its own deletes the character preceding the cursor, or any +highlighted text (see below). + +Left/Right Move the cursor left or right along the line being edited. + +Up/Down Recall previous commands. The up and down arrow keys move backwards +and forwards respectively through the last 32 commands (maximum) that +were issued. + +Esc Esc on its own deletes the entire line. + + +This keypress also breaks out of a batch file or a long listing, and will +cancel a warT command + + +There are also several special keypress combinations: + + +Shift-Del +Psion-Del +Shift-Psion-Del +Shift-Left + + +Shift-Right + + +Psion-Shift-Ctrl-Left +Psion-Shift-Ctrl-Right + + +Ctrl-Left + + +Ctrl-Right + + +Psion-Left +Psion-Right +Psion-Down + + +Psion-Up + + +Deletes the following character, (if no text is highlighted). +Deletes from the cursor to the start of the line, (if no text is highlighted). +Deletes from the cursor to the end of the line, (if no text is highlighted). + + +Moves the cursor left, highlighting (in reverse video) all characters passed. +If the Shift key is kept depressed and Right is then pressed the text will be +unhighlighted again as the cursor passes. + + +Moves the cursor right, highlighting (in reverse video) all characters +passed. If the Shift key is kept depressed and Left is then pressed the text +will be unhighlighted again as the cursor passes. + + +Highlights (in reverse video) the current word. + + +Highlights (in reverse video) the current line. + +This is somewhat pointless when editing batch files, since all you can then +do is delete the line (which is more easily done by simply pressing Esc). It +is supplied for the benefit of user-developed applications, which have +access to the same editor. + + +Moves the cursor to the beginning of the current word being edited, or of +the preceding word if already in that position. + + +Moves the cursor to the beginning of the next word to the right, or to the +end of the line if already on the last word. + + +Moves the cursor to the beginning of the line being edited. + + +Moves the cursor to the end of the line being edited. +Recalls last command issued. + + +Recalls earliest recallable command. + + +WORKABOUT PROGRAMMERS REFERENCE + + +Shift-Esc The "Help" hotkey combination. It brings up the Command Processor Help +menu. + +Ctrl-Shift-Esc The "Help index" hotkey combination. It is used to bring up a general Help +index. + +Psion-Tab The "Task" hotkey combination. It allows switching between the + + +Command Processor and other tasks, (if any). + + +Ctrl-C The "Break" hotkey combination cancels a WAIT command. It has the +same effect as pressing Esc. + + +Ctrl-S The "Pause" hotkey combination. Pauses a batch file or a long listing. + + +Pausing the screen display + + +All commands automatically pause when a screenful of information has been displayed. In all cases, +pressing Enter resumes the display. The Esc key can usually be used to terminate the command listing. + + +Commands do not pause when being executed within a batch file. + + +Running multiple System Interfaces + + +It is not possible to run an additional copy of the Command Processor. If this is attempted by entering at +the command line prompt of the Command Processor: + + +start sys$cmdp +a "File already exists" dialog will appear. + + +It is, however, possible to run the System Screen at the same time as the Command Processor. To do this +enter at the command line prompt of the Command Processor: + + +start sysS$gsys + + +The Task key combination (Psion-Tab) can then be used to switch between the two system interfaces, (and +any other tasks that are also running). + + +Only one copy of the System Screen may be started - if one is already running a "File already exists" +dialog will appear. It is not possible to install the Command Processor in, or to start the Command +Processor from, the System Screen. + + +Files and directories + + +File In Use error messages + + +If any Workabout application has a file open, no other application is allowed to alter that file in any way. +For this reason, some file commands may unexpectedly fail, when issued from the Command Processor. + + +For example, it is impossible to make a complete copy of all the files in a directory if any one (or more) of +these files is in use by another application. Commands to delete or rename such a file will likewise report +an error. + + +Default path and current directory + + +Unlike MS-DOS, in which there is always a current logged directory for each different drive (and so there +are as many current directories as there are drives), in EPOC there is only one current directory for each +running process. Indeed, instead of referring to a current directory, it is preferable to refer to the current +path, since the drive is included too (and the filing system). + + +Unlike on the Psion HC, there is no single command to set the default path on the Workabout. The drive +letter followed by a colon should be used to set the current drive in the Command Processor or in batch +files, and the cb command to change the current directory. + + +Note that if the current path is awork\, the effect of typing cd b:\play is the same in the Workabout +Command Processor as in MS-DOS, but is limited to local drives. + + +3 WORKABOUT COMMAND PROCESSOR + + +However, in EPOC, there is a different current path for each current application. Changing the path in one +application does not alter the path in another application. This may be regarded as a significant +improvement over MS-DOS, where the currently logged directories in the command processor are often +annoyingly altered by running (synchronously!) another process. By the time the second process has +terminated, the MS-DOS command processor may have been logged to a different drive and a different +directory. + + +Note that any changes to the path of the Command Processor inside a batch file will continue to have +effect after the termination of the batch file, since no new process is run up just by virtue of a batch file +being executed. + + +Specifying file names as command parameters +In all, a full file specification is regarded as having five parts: +e 6A filing system (e.g. loc:: or rem::). +e =A drive or device (e.g. b:). +e =A path (e.g. \ or \accounts\jan\). +e =A filename (e.g. job). +e = An extension (e.g. .img). + + +Frequently, it is possible to omit part of the full specification of the path of a file, when giving a filename +as a parameter to a command in the Command Processor. Any missing parts of the filename will be filled +in from the current path. In the Alphabetical listing below fi1espec implies a full file specification as +listed above, filename means the name of the file only. + + +For example, if the current path is m:\img\, the command attrib job.img -r operates on the file with +full specification m:\img\job.img. However, the command att b:\backup\job.img operates, naturally +enough, on the file b:\backup\job.img - regardless of the current path. + + +If the current directory on b: is \img\, the command attrib b:job.img operates on a file b:\img\job.img +(if one exists) - not on any file job.img in the root directory of b:. The reason for this is that the filename +b-job.img 1s interpreted as having only the three parts: + + +e =a drive (b:) + +e a basic name (job) + +e an extension (.img). +Since the path component is missing, this is taken from the current path for the drive. +To specify a file job.img on the root directory of b:, type: + +b:\job.img +including the crucial \ character that indicates the path. + + +Specifying paths as command parameters + + +Just as it is often possible to omit part of the full specification of the path of a file, when giving a filename +as a parameter to a command in the Command Processor, so also is it often possible to omit part of the full +specification of a path (or directory name), when issuing a command such as ca, ma, or rd that expects a +directory name as a parameter. Any missing parts of the directory name will be filled in from the current +path. + + +Thus if the current drive is m: and the current path is \img\, the command ma tools is equivalent to +md m:\img\tools. Likewise cd tools 1s equivalent to cd m:\img\tools and rd tools is equivalent to +rd m:\img\tools. + + +When specifying a path, a trailing backslash can generally be used to clarify that a name is a directory +rather than a file. + + +WORKABOUT PROGRAMMERS REFERENCE + + +Wildcards + + +As in DOS, the wildcards ? and « may be used in the file name and/or the extension components of a file +specification, where ? represents any single character and * represents zero or more characters. + + +The use of « differs from its use in DOS in that, on the Workabout, it is possible to use, for example: +a*b.* +to select all files whose file name starts with a and ends with b. In DOS, a*b.* has the same effect as ax. *. + + +The requirements of generality + + +Evidently, although some of the syntax of commands such as ma and rd is similar to that of corresponding +commands in DOS, in other aspects the requirements of the Workabout Command Processor syntax for +these functions may be found more restrictive than in DOS. + + +In fact, the extra restrictions stem from a central design feature of the EPOC operating system - the +requirement for applications to be able directly to address files on a remote computer, where the remote +filing system may well be other than DOS. Alternative remote filing systems that need to be borne in +mind, as well as just DOS, include Unix, Vax VMS, and the Apple Macintosh operating system. + + +Thus if the Workabout is connected to an Apple Macintosh computer, the following could be entered at +the command line: + + +dir rem: :hd40:Workdevp: stock + + +Accordingly, the Workabout Command Processor does not simply approach filenames and path +specifications in terms of prescence or absence of backslashes. For example, were the Command Processor +to insert a backslash at the end of the above command, "on behalf of the user", this would, most decidedly, +not be what the user intended. Instead, the approach is much more general, in terms of the five part +breakdown of filename specifications discussed two sections previously. + + +wom + + +It should be noted that Psion computers allow the use, for example, of the "+" character in filenames, +which is not allowed in MS-DOS for instance. For portability between filing systems and applications on +different manufacturers machines it is recommended that only letters and numbers are used in filenames. +At the very least filenames should be restricted to the MS-DOS naming convention. The allowed +characters in an MS-DOS filename are: + + +A-Z2 a-z 0-9 $ %® '" - @ { } ~ * 1! # ( +) & +MS-DOS filenames are case insensitive, (upper and lower case letters are treated the same). + + +Different DOS versions handle accented characters differently. It is recommended that accented characters +are not used in filenames. + + +Filenames that are keywords, the names of ports or device drivers, etc. on the Workabout or any remote +system, should also be avoided, e.g. COM1, LPT2, etc. + + +Similarly, the Workabout provides only limited support for the syntax of "double dot" (for the parent +directory) and "single dot" (for the current directory). + + +This extra discipline has its occasional drawbacks. However, the advantages that it brings with it are an +important part of the vital inter-connectable feature of the Workabout. + + +Alphabetical listing +Notation +This list of commands uses the following syntax: +COMMAND supplied-parameter [optional-parameter | optional-parameter] +or: +COMMAND [optional-parameter] {supplied-parameter | supplied-parameter} + + +Items shown in square brackets ( [ ] ) are optional. To include optional information, type only the +information within the brackets. Do not type the square brackets themselves. + + +3 WORKABOUT COMMAND PROCESSOR + + +The use of the vertical bar (| ) symbol between parameters means that one parameter OR the other +parameter can be used, (but not both). Type only one parameter. Do not type the vertical bar itself. + + +If there are alternatives but one or other must be included, the options are enclosed in curly brackets ( { } +), if required for clarity. Type only one parameter. Do not type the curly brackets themselves. + + +Shortened versions of commands are not available. In the above (generalised) example, com would not be +an acceptable shortened form of commanp. The Workabout Command Processor thus differs from the Psion +HC Command Processor which does allow command abbreviations. + + +Commands can be typed in any combination of lower and upper case. For example, except where clearly +stated to the contrary below, variants such as echo on and echo on are completely equivalent. + + +A command keyword must be separated from any following parameter by at least one space character. + + +Default values may be assumed if some options are not supplied. Default values of particular commands +are given in the individual command descriptions which follow. + + +Note: + +The following list actually contains entries that are not really commands of the Command Processor, in +the strict sense, but are just the name of a program in the ROM, for example Linx. However, this +distinction may seem irrelevant to the user, and so, for convenience, these commands are listed as well. +DOS calls these external commands. + + +ATTRIB Set or clear file attributes + + +ATTRIB [system::][drive:][path]filename[.extension] [+a|-a] [+s|-s] [+h|-h] [+r]|-r] +Set or reset the archived (a), system (s), hidden (h) and/or read-only (xr) attributes of a file. + + +For example, attrib -a +s list.dat clears the archived attribute and sets the system attribute of Jist.dat, +without altering its hidden or read-only attributes. + + +For each of h, s, a, and r, a prefix of - clears the corresponding attribute, and a prefix of + sets it. The four +attributes can be specified in any order, and any combination of the four bits can be set or cleared at once. +Omitting all four is pointless: nothing will happen. + + +The attris command accepts a file specification containing wildcards. + + +Note that the ptr command includes the attributes of files as part of its display. + + +CALC Run the calculator application + + +[START] CALC +Run the Calculator application, Calc. +If preceded by start, Calc will be run asynchronously. + + +Note: +Help on using the Calculator application is available by pressing Shift-Esc. + + +For full information on using the Calculator application, see the Workabout User Guide. + + +CALL Call a batch file from inside another batch file +[CALL ] [system::] [drive:] [path]batchfile[.extension] [batch-parameters] +Calls a batch file from inside another batch file. + + +Omitting the caLL command and just using the file specification "chains" the named batch file, and does +not return to the current batch file on completion. + + +WORKABOUT PROGRAMMERS REFERENCE + + +CD Display or alter current directory +CD [system::] [drive:] [path] + + +Change to a different path, or (if path is omitted) displays the current path. Note that system: : can only +be loc::. + + +For example, to change the current directory from \work\product\ to \work\admin\, type: +cd \work\admin\ + + +To move to a directory below the current one, only the path from the current directory needs to be entered. +So to change from \work\admin\ to \work\admin\forms\, the following command could be used: + + +cd forms\ + + +The trailing backslash in the above commands can be omitted. Thus cd forms instead of cd forms\ will +do the same thing. + + +Use cb [drive:]\ to change to the root directory of a drive, or of the current drive if drive: is omitted. +For example, type: +cd b:\ +to change to the root directory of b:. +Typing cd b: changes nothing and just displays the current path for b:. +To change drive use: + + +drive: + + +CHDIR Change directory + + +CHDIR [system::] [drive:] [path] + + +Changes to a different path, or (if path is omitted) displays the current path. This command is exactly the +same as cD. + + +CLS Clear the screen + + +Clear the screen, leaving the > prompt in the top left corner. + + +COMMS Run the communications application + + +[START] COMMS [system::] [drive:] [path] [filename[.extension] ] +Run the communications application, Comms. +If preceded by start, Comms will be run asynchronously. + + +If no file specification is provided, and the current drive is m:, (and comms.sco does not already exist), a +dialog is presented asking: + + +Create "M:\SCO\COMMS.SCO"? + + +If "Y' is then pressed the file m:\sco\comms.sco will be created, along with a file m:\scr\comms.scr, for +later use. Note that files with the extension .scr are editable communications scripts files, and files with +the extension .sco are translated communications script files. The user is then presented with the terminal +emulation screen. + + +Otherwise, if comms.sco does already exist, then no dialog is presented. Note that it does not matter +whether comms.scr exists or not. + + +If any system, drive or path is provided, but no filename, the comms.sco file will be placed in the specified +location. The default directory for translated communications script files (extension .sco) is \sco\, and it is +recommended that this is where all files of this type are kept. Note that the default directory for +untranslated (editable) communications script files (extension .scr) is \scr\, and keeping all files of this +type in their directory is also recommended. + + +3 WORKABOUT COMMAND PROCESSOR + + +If a filename is given, a .sco file and a .scr file of that name will be created (as above) depending on +whether they currently exist or not. + + +An extension to the filename may be provided that differs from sco, but this is not recommended, since it +would make identification of the file type difficult. + + +Note: +Help on using the Communications application is available by pressing Shift-Esc. + + +For general information on using the Communications application, see the Workabout User Guide, and for +full details refer to the Psion Series 3 3Link (RS232) manual. + + +COPY Copy file(s) + + +COPY source_filespec destination_filespec [/s] [/y] + +Copy one or more files or directories, possibly changing their names in the process. + +If the /s flag is used then all subdirectories of a specified source directory will also be copied. +The /y switch allows overwriting without confirmation. + + +Any part of the target filename that is not specified, (for example, the extension), and which cannot be +filled in from corresponding parts in the current drive and path, is taken from the corresponding part of +the first pathname. + + +If the destination filename is that of an existing file, then that file will be overwritten. Unless /y is +specified, a "File exists" dialog appears, requesting confirmation, before the file is overwritten. + + +The wildcards « and ? can be used to copy multiple files. +For example: +copy fred.* a:\jim.* + + +copies all files with a file name of fred, but any extension, from the current directory into the root of a.\, +renaming them, without altering the extension in the process. + + +As a possibly surprising example, if the current drive is m: and the current path is \, the command +copy a:\file.lis file.oid has the effect of copying the named file to m-\file.old. + + +The names of the source files are listed on the screen as they are copied. + + +A file cannot be copied onto itself. If an attempt is made to do this, the copy command quits, and an error +message such as the following is displayed: + + +Copy failed : 0 files + + +DATA Run the database application +[START] DATA [system::] [drive:] [path] [filename[.extension] ] + +Run the database application, Data. + +If preceded by start, Data will be run asynchronously. + + +If no file specification is provided, and the current drive is m-:, (and data,dbf does not already exist), a +dialog is presented asking: + + +Create "M:\DAT\DATA.DBF"? +Otherwise, if data.dbf does already exist, then it will be presented directly for editing. + + +If any system, drive or path is provided, but no filename, the data.dbf file will be placed in, (or retrieved +from), the specified location. The default directory is \dar\, and it is recommended that this is where all +database files are kept. + + +If a filename is given, a .dbf file of that name will be created (as above) and/or presented for editing +depending on whether it currently exists or not. + + +WORKABOUT PROGRAMMERS REFERENCE + + +An extension to the filename may be provided that differs from .dbf, but this is not recommended, since it +would make identification of the file type difficult. + + +For general information on using the Database application, see the Workabout User Guide. + + +This application may be useful for quickly looking at or manipulating OPL data files. There are, however, +certain restrictions and differences that must be borne in mind. See the Database files chapter of the SIBO +OPL Technical Reference manual for further details. + + +Note: +Help on using the Database application is available by pressing Shift-Esc. + + +DATE Display date + + +DATE + + +Display the current date in the default format, or that specified by the most recent szETDEF or menu +command. + + +The default display format is: +dd/mm/yy +For example 12/10/95 will be displayed if the current system date is 12 October 1995. + + +If the day of the month or the month number itself has only a single digit, a leading zero is displayed. The +first day of January 1996 is displayed as: + + +01/01/96 +Use the Time and Date option on the Time menu to change the date. + + +Use the setpEF command or the Formats option of the Time menu to change the format in which the date +is displayed. + + +DEL Delete file(s) + + +DEL [system::][drive:][path]filespec [/s] [/y] + +Delete the specified file or files. + +If the /s flag is used, all subdirectories and the files in them are deleted. + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files + + +To delete more than one file at a time, the wildcards * and/or ? can be used. Alternatively, the following +deletes all files in the directory temp (in the current path): + + +del temp\ + + +The trailing backslash may be omitted, in which case a dialog is presented: "Delete all files in directory?". +The Y key should then be pressed to carry out the deletion. + + +As files are deleted, the names of the files deleted are listed on the screen. + + +The erase command is exactly the same as peu. See also the command rp, which deletes directories. + + +DIR Full directory listing + + +DIR [system::][drive:] [path] [filespec] [/s] [/b] + + +List all the specified files in a directory, together with their sizes, the time and date of their last +modification, and their attributes. + + +The listing pauses automatically after each screen of information, prompting the user to press enter to +continue. + + +The wildcards « and ? can be used in the file specification. +The /s flag causes all subdirectories to be listed as well. + + +The /b flag causes bare (filenames only) output to be displayed. + + +3 WORKABOUT COMMAND PROCESSOR + + +ECHO Display message, set or display echo mode +ECHO [[text]|[ON | OFF]] +Display the message text, or set the echo mode in batch files, or display the current echo mode. + + +For example: + + +echo Processing Displays the message Processing on the next line of the screen. +echo on Switches the echo mode in batch files to ON. + +echo off Switches the echo mode in batch files to OFF. + +echo Displays the current echo mode in batch files, e.g.: + + +Echo is OFF +or +Echo is ON + + +EDIT Run the text editor + + +EDIT [system::] [drive:] [path] filename[.extension] +Run the text editor program. + + +The three different editors for batch files, OPL programs and communications scripts are implemented as +aliases of the Word application. + + +A filename must be given (no default names are provided). + + +If no extension is given then an alias of Word that behaves as a batch file editor is started, and the +extension defaults to .btf: In this instance there are no Translate and Run menu options available, since +they are not relevant. + + +If the filename is given an extension of .op/ then the Word alias behaves as an OPL program editor. If the +filename is given an extension of .scr then it behaves as a communications script editor. In both these +instances, Translate and Run menu options are available (translation is different for .scr and .op!l files). + + +If a path is not given then \bif\, \op/\ or \scr\ is assumed as the directory for a batch file (.btf) an OPL +program (.op/) or a communications script (.scr) respectively. + + +If any other extension is given for the filename and no path is specified then the file will be put in a \btf\ +directory. + + +If you supply a partial path, the Command Processor will try to use the results of your last cp command on +the relevant drive. + + +If a filename is not supplied, the error message "Too few parameters" is displayed. +If a filename is given, but no extension: +e = Ifa file called filename. btf does not already exist, then a dialog is presented, asking: +Create "M:\BTF\FILENAME.BTF"? +If Y is then pressed the editor will display a blank file of name filename. btf, ready for editing. + + +e = Ifa file called filename. btf does already exist, then no dialog is presented, and the existing file +filename. btf is presented for re-editing. + + +Similar dialogs and messages are presented for files with .scr and .opl extensions. +When saved, or the editor is exited, files are stored in the specified directory. + + +Notes: + +The ep1T command starts an alias of the Word application. When epit (or sTART EDIT) is used the +process started will appear in an Lproc or Ls&c listing as an instance of Word. As well as using EDIT +directly from the Command Processor or from a batch file, aliases of Word can be started from one of the +editor icons in the System Screen. + + +WORKABOUT PROGRAMMERS REFERENCE + + +The first time that EpIT is used to run the batch file editor, the program editor or the communications +script editor, a \wdr\ directory will be created (if it does not already exist). This directory is used for the +storage of printer drivers and template files. Furthermore, the first time the program editor is used the +default template default.o is stored in this directory. + + +Help on using the Editors is available by pressing Shift-Esc. All the editors function in the same way. + + +For further information on the various editors see the Workabout User Guide. There is more information +on the Communications Script Editor in the Psion Series 3 3Link (RS232) manual. + + +ERASE Delete file(s) + + +ERASE [system::] [drive:][path]filespec [/s] [/y] + +Delete the specified file or files. + +If the /s flag is used, all subdirectories and the files in them are deleted. + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + + +To delete more than one file at a time, the wildcards * and/or ? can be used. Alternatively, the following +deletes all files in the directory temp (in the current path): + + +erase temp\ + + +The trailing backslash may be omitted, in which case a dialog is presented: "Delete all files in directory?". +The Y key should then be pressed to carry out the deletion. + + +As files are deleted, the names of the files deleted are listed on the screen. + + +The command pet is exactly the same as grass. See also the command rp, which deletes directories. + + +ERRLEVEL Display error state + + +ERRLEVEL +Display the error state, which may be TRUE or FALSE, e.g.: +Errorlevel is FALSE + + +It reports whether the last command or process to finish left ERRORLEVEL Set aS TRUE Or FALSE. This may be +useful when debugging batch files. + + +EXIT Terminate the Command Processor +EXIT +Present a dialog offering options to terminate the Command Processor or cancel the command. + + +On confirmation of an ExT command typed directly into the Command Processor (or of the selection of +the Exit option from the Special menu) the Command Processor is terminated. If there is no other task +running on the machine, the Workabout will then automatically re-launch the Startup Shell process, as +explained in the chapter [Introduction to the Workabout. If one or more other tasks are running, the +machine will switch tasks to whichever running application was last used. + + +If the exrT command is executed from a (nested) batch file, all levels of batch processing are terminated +immediately and the confirmation dialog presented. On confirming the Ex1tT command, the Command +Processor terminates in the same way as when ex1T is typed directly into the Command Processor. + + +FILES List open files + + +FILES [system::] [drive:] + + +List all open files on the specified drive. For each file the full file specification, the program using the file +and its process number are given. + + +If the drive is not specified, open files on the current drive are listed. + + +3 WORKABOUT COMMAND PROCESSOR + + +FOR Run a command for the files in a set +FOR Svariable IN (set) DO command [parameters] +Run a command for each file in a specified set of files. + + +The replaceable parameter svariable is used by the ror command to hold the name of each file as it is +being processed. + + +The set of files is specified by set. The wildcards * and ? can be used. The parentheses are always +required. + + +The command to carry out for each file in the set is specified by command. The parameters or switches for +the specified command are given by parameters, if the command needs any. + + +To use the ror command in a batch file, specify ssvariable instead of variable. +For example, to asynchronously run all application files in the a:\app\ directory: +for %f in (a:\app\*.app) do start %f +From within a batch file, this same sequence of operations would be performed by the line: + + +for %%f in (a:\app\*.app) do start %%f + + +FORMAT Format and re-label local volume +FORMAT [drive:] [volname] + + +Format a local volume i.e. a RAM or Flash SSD in drive A: or B:, or the internal drive M:RAMDRIVE. +It also renames the volume with the optional voiname. + + +The command detects the type of SSD and places the appropriate format information onto the disk. This +information differs for Flash and RAM SSDs. + + +For example, format a: will format the SSD in drive A: . + +The command, format b:data will format the SSD in drive B:, giving it the volume name "DATA". +If drive: is omitted, a dialog appears asking if you want to format M:RAMDRIVE. + +Note that, once the format command is started, no warning is given before the formatting takes place. + + +The mere fact that there are read-only files on an SSD or the internal drive will not prevent the it +from being formatted. However, if an SSD has the write-protection switch set, it will not be possible to +format it. + + +The rormat command will fail if there is no SSD in the specified drive. In this case, the Format request +will fail with the error message "Format failed. Not ready". + + +Another reason for Format being disallowed for a disk would be if there are any open files on it. In this +case, the rormaT request will fail with the error message "File or device in use". + + +If an SSD needs to be to be given a volume name at a later date, then the LaBEL command may be used. To +find the current volume name, use the von and/or ptr commands. + + +GOTO Jump to label in batch file + + +GOTO label + + +Jump to the label 1abe1 in a batch file. + + +HELP List commands or get help +HELP [command] +List the available commands, or supply help on a specific command. + + +Press Shift-Off for access to the Help System, or Ctrl-Off for the Help Index. + + +WORKABOUT PROGRAMMERS REFERENCE + + +IF Run command conditionally + + +IF [NOT] {ERRORLEVEL | stringl==string2 | EXIST filespec} command [command_parameters] +Conditionally run a command or executable file, depending on one of three possible specified conditions. + + +e ©The value of ERRORLEVEL., for example: +IF ERRORLEVEL DEL *.tmp + + +Note that ERRORLEVEL can only be TRuE or FALSE. The DOS syntax: +IF ERRORLEVEL n ... +is not supported + + +e Whether two strings (string1 and string2) are equivalent, for example +IF ?$1==? DEL *.tmp + + +e Whether a specified file exists, for example: +IF EXIST a:\img\tmp.img DEL a:\img\tmp.img + + +KILL Kill a process + + +KILL procname [/y] + + +Kill the first process found to match the specification in procname. Note that this is intended for +emergency use only. + + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files, but should be +used with extreme caution. + + +To kill a specified instance of a number of running tasks, all with the same name, the exact process name +must be found out and used. For example: + + +kill job.$09 +or +kill job.$14 + + +If there are no processes matching the specification, a notifier stating: + + +Unknown process "Procname" +will be presented. Use the tproc command to give the full process names of all current processes. + + +A confirmation dialog is presented if a process matching the specification is found, reminding the user +that x11 is for emergency use only: + + +Kill "Procname" +(Emergency only) + + +Notes: + +KILL should only be used as a last resort, as it does not allow the process to tidy up before exiting. This is a +problem with the Link application, for example, which starts a number of sub-processes that will not be +shut down if Link is stopped with x1... To shut down a process, stop should normally be used in +preference to KILL. + + +The xrLi command is designed for use with badly behaved (perhaps partially developed) user-written +programs. Built in Psion applications should be stopped using the options available from their menus, +from the System Screen or by use of the stop command. + + +LABEL Add/alter disk volume name + + +LABEL [drive:] [volname] +Label the volume in the specified drive with the label voiname. + + +If the drive is omitted then the current local volume (i.e. an SSD in the current drive, A: or B:; or the +internal ramdrive M:), will be re-labelled with the label voiname. + + +3 WORKABOUT COMMAND PROCESSOR + + +If the name volname is omitted then a "Delete label" dialog will appear (unless the volume in the specified +drive, or current drive, has no label). + + +For example: +label a:backup +Will re-label the SSD in drive A: as "backup". + + +If the command 1abei a: is now used then the dialog "Delete label "A:BACKUP"' will be displayed. +Pressing Y then deletes the label, pressing N or Esc abandons the command. + + +LINK Start Link program + + +LINK [-b] [-p] + + +Starts the Link communication software on the Workabout. It is always run asynchronously, so start is +never needed. + + +If no parameters are supplied, the Link software is started with the default settings, or those used on the +last occasion that Link was started, whether by means of the LInx command or via the dialogs available in +the System Screen and Command Processor menus. + + +The value of baud sets the baud rate. Possible values range from 19200 to 50 inclusive - for a full list of +intermediate values, see the Serial Port chapter of the I/O Devices Reference manual. In the absence of +the baud command line parameter, the baud rate defaults to 19200. + + +The only time it is necessary to specify port is if there are serial expansion devices in the Workabout. +¢ -p1 means to use the expansion RS232 port, (port A) + + +e -p3 means to use the LIF socket (LIF Converter with attached 3Link inserted) as an RS232 serial +port (port C) + + +Otherwise, if port is not specified, the Link software simply uses the first available port in alphabetical +order. + + +Other parameters are also possible, but are omitted from the present description. See the chapter Mclink, +Mcprint, and Slink in the Additional System Information manual. Just typing 1ink should suffice in the +majority of cases. + + +To terminate the Link software at some later stage, type: +stop link + +A Yes/No dialog will be presented asking: +Stop "Link"? + +y should then be pressed to stop Link. + + +To discover whether or not Link software is running, type lproc 1ink. Note, however, that if the 1ink +command is issued while Link is already running, no harm will be done. + + +See the section Connecting to other computers in the chapter Introduction to the Workabout, for more +details. + + +LLDEV List logical device drivers + + +LLDEV [device_spec] + + +List all logical device drivers that match the supplied specification. The list includes all ROM-resident +logical device drivers, as well as external ones that are currently loaded. + + +If device_spec is omitted, all existing logical device drivers are listed. +For example, entering + + +lldev con + + +WORKABOUT PROGRAMMERS REFERENCE + + +displays: + + +Logical devices matching: con +CON (unlimited units) +Matches found 1 + + +The value given for units is the number of channels that the corresponding logical device driver can +support. For the console device (con: ) an unlimited number of channels can be opened. + + +LPDEV List physical device drivers + + +LPDEV [device_spec] + + +List all physical device drivers that match the supplied specification. The list includes all ROM-resident + + +physical device drivers, as well as external ones that are currently loaded. +If device_spec is omitted, all existing physical device drivers are listed. +For example, entering + +lpdev fsy +displays: + + +Physical devices matching: fsy +FSY.REM + +FSY.LOC + +FSY.ROM + +Matches found 3 + + +listing the three ROM-resident filing system device (fsy) drivers - for rem::, loc::, and rom::. + + +LPROC + + +LPROC [process_spec] +List information about all specified processes. The information listed is: +e The full process name (in the form procname.$07). +e The size, in bytes, of the process data segment (given in hexadecimal). +e The current state of the process. +The total number of matches found is then displayed. +If process_spec is omitted, information is listed for all current processes. +Possible values of the state of the process are: + + +CURRENT The process is currently receiving CPU time. + + +List processes + + +READY The process has some events ready to process, as soon as the CPU is given to the + + +process by the multi-tasking scheduler. + + +DELTA The process is "sleeping" (e.g. as a result of calling pausz with a positive +parameter). + +sus The process has been suspended. + +SEM The process is waiting for some event to happen. + + +Additionally, the text wsusp will be displayed if the process is waiting to be suspended. + + +3 WORKABOUT COMMAND PROCESSOR + + +For example, entering 1proc may produce the display: + + +Processes matching: * +SYSSNULL.$01 0300 READY +SYSSMANG.$02 ODAO SEM +SYSSFSRV.$03 1320 SEM +SYSSWSRV.$04 4DCO SEM +SYSSSHLL.$05 14CO SEM +SYSSCMDP.$06 4BCO CURRENT +Matches found 6 + + +As a further example, entering lproc sys$sh11 may produce the display + + +Processes matching: sys$shll +SYSSSHLL.$05 14C0 SEM +Matches found 1 + + +One common use of the 1proc command is to check whether Link software is currently running: 1proc +link. + + +Notes: + +For a process that is an alias of another program, using sTART procname (or just procname on its own) will +start a process that appears to LpRoc as an instance of the base process. For example, all text or program +editors are aliases of the Word application. In consequence, processes started with Ep1T or sTarRT EDIT all +appear as instances of Word in an tprRoc listing. + + +Note also that Sheet is the user-visible name of the Sh3 process. Thus, a process started with starRT SHEET +or with sHEET will appear as an instance of Sh3 in the proc listing. + + +LSEG List segments + + +LSEG [process_spec] +List all memory segments currently in use by the specified process(es). + + +If process_spec iS omitted, the listing will include the memory segments used by all currently running +processes. + + +The information listed about each memory segment is: +e Its segment address. +e Its size in paragraphs (one paragraph is sixteen bytes). +e Its access count. + +Values are displayed in hexadecimal. + +The total number of matches found is then displayed. + + +At the end the display, the total size in paragraphs of all the free segments is given (this gives the same +value, when converted into kilobytes, as the mzm command). + + +For example, entering 1seg may produce the display: + + +Segments matching: * +SYSSNULL.$01 046E 0030 01 +SYSSMANG.$02 049E OODA O01 +SYSSWSRV.LDD 0578 O0E3 01 +SYSSFSRV.$03 065B 01B7 01 +SYSSWSRV.S$04 0812 0560 O01 +SYSSSHLL.$05 OD72 014C O01 +SYSSCMDP.$06 OEBE O4BC 01 +Matches found 7 + +Total free segments = 6CFO + + +Notes: + +For a process that is an alias of another program, using sTaRT procname (or just procname on its own) will +start a process that appears to LsEG as an instance of the base process. For example, all text or program +editors are aliases of the Word application. In consequence, processes started with Ep1T or sTarRT EDIT all +appear as instances of Word in an tszc listing. + + +Note also that Sheet is the user-visible name of the Sh3 process. Thus, a process started with sTaRT SHEET +or with sHEET will appear as an instance of Sh3 in the tsze listing. + + +WORKABOUT PROGRAMMERS REFERENCE + + +MD Make directory +MD [drive:]path +Make a directory. + + +A directory will be created as a subdirectory of the current directory, unless a different path is explicitly +specified. + + +It is possible to omit the trailing backslash from the path specification. +The following commands both create a directory named \work\ in the root directory of the current drive: + + +md \work\ +md \work + + +The command mxp1R (which is identical) is also available. + + +MEM Display free memory +MEM +Display the amount of free RAM, in kilobytes, that is available to programs. + + +Note that this, in general, exceeds the amount of bytes free in m:, as reported by a pIR command. The +discrepancy is because some parts of internal memory are reserved for code and data segments; not all of it +can be allocated to the contents of m-:. + + +MKDIR Make directory + + +MKDIR [drive:]path +Make a directory. + + +A directory will be created as a subdirectory of the current directory, unless a different path is explicitly +specified. + + +It is possible to omit the trailing backslash from the path specification. +The following commands both create a directory named \work\ in the root directory of the current drive: + + +mkdir \work\ +mkdir \work + + +The command mp (which is identical) is also available. + + +PAUSE Suspend batch file processing +PAUSE [text] +Suspend batch file processing. +The message text is displayed (if supplied). +The prompt +Press Enter to continue... +is always shown. + + +When Enter is pressed batch file processing continues by executing the next line of the current batch file. + + +QUIT Terminate current batch file + + +QUIT + + +Terminate the current batch file. If batch files are nested, batch processing will continue at the line +following that which contains the call to the batch file that executed gut. + + +The command has no effect if typed directly into the Command Processor. + + +3 - 20 + + +3 WORKABOUT COMMAND PROCESSOR + + +RD Remove directory +RD [drive:]path [/y] + +Delete a directory, including any files in it (and subdirectories). + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + + +Note that, in contrast to MS-DOS, there is no requirement to delete all the files in a directory before +removing the directory. + + +In another difference from MS-DOS, it is perfectly possible, in the Workabout Command Processor, to +remove the directory where the current path is. All that will happen is that subsequent commands such as +dir may fail until such time as the current path is changed. + + +As files and directories are deleted, their names are listed on the screen. +The ra command does not accept a wildcard specification. + + +The identical command rmprrR is also supported. + + +REASON Get the cause of the last system shutdown +REASON +Display a numeric code indicating the cause of the last system shutdown, as follows: + + +0 The system started up for the first time (or after a period during which all power had been +removed, including the Lithium back-up battery). + + +1 The hardware forced a shut-down because the main battery voltage became too low. This +should not happen because the system software receives a non-maskable interrupt if the +voltage drops below a certain threshold (but not low enough for the hardware to force a +shut-down). This interrupt code automatically switches the hardware off. However, if the +clean-up takes too long (because of a poorly designed device driver, for example) the +hardware will force the machine off before the interrupt completes - in which case REASON +returns 1. The environment variables and the contents of m: are preserved. + + +3 Either: +The user pressed Psion-Ctrl-Del to perform a soft reset. The environment variables and the +contents of m: will have been preserved. + + +Or: +This reason is also given if the system was reset because a serious fault occurred while +executing code in the operating system kernel. This could result from: + + +a bug in the operating system or a system process; +a program bug that managed to overcome the operating system's defences +a hardware problem such as a RAM fault. + + +The environment variables and the contents of m: will be preserved (unless the system +detects a memory corruption). + + +4 The user pressed Shift-Psion-Ctrl-Del to perform a hard reset. The environment variables +and the contents of m: will have been cleared. + + +For example, if the machine has previously lost all power, entering reason will return: + + +Reset code: 0 + + +REM Comment (remark) in batch file +REM [text] + +Comment (remark) in batch file. Note that rem must be followed by a space. + +The text characters become a comment in the batch file. + + +Any text on a line preceded by rem becomes a comment that is not executed when the batch file is run. +This is useful for temporarily removing a command line, for example, when debugging a batch file. + + +WORKABOUT PROGRAMMERS REFERENCE + + +REN Rename file(s) + + +REN [system::] [drive:][path]filespec filename +Change the name of a file or files. +The command renames all files matching filespec - which can include wildcards. +For example, the command: +ren work.* play.* + + +changes the names of all files called work in the current directory (regardless of extension) to play, with +the extension being preserved across the rename. + + +As files are renamed, they are listed on the screen. + + +Because it is not possible to rename files from one directory to another, the command fails if any path +specified with £i1ename (explicitly or implicitly) differs from that of rilespec. + + +It is not possible to rename a file to have the same name as a file that already exists. + + +RMDIR Remove directory + + +RMDIR [drive:]path [/y] +Delete a directory, including any files in it (and subdirectories). +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + + +Note that, in contrast to MS-DOS, there is no requirement to delete all the files in a directory before +removing the directory. + + +In another difference from MS-DOS, it is perfectly possible, in the Workabout Command Processor, to +remove the directory to which the current path is set. All that will happen is that subsequent commands +such as dir may fail until such time as the current path is changed. + + +As files and directories are deleted, their names are listed on the screen. +The rmdir command does not accept a wildcard specification. + + +The identical command ro is also supported. + + +SET Display, set or delete environment variable + + +SET [[var[=[value]]]| [varspec] ] +Display or set the value of an environment variable, or delete the variable. +With no parameters, the values of all current environment variables are displayed. + + +If the environment variable var is given, but without any trailing equals (=) sign, the value of the +environment variable is displayed. + + +If the equals sign (=) is present, followed by a value, the environment variable var is set to the specified +value. + + +If the equals sign is present, but value is omitted, the environment variable var is deleted. + + +If the environment variable specification varspec is given, the values of all environment variables +matching the specification are listed. + + +For example: + + +set last Displays the value of environment variable 1ast. + +set last=34 Sets the value of 1ast to the string 34, creating it if it did not previously +exist. + +set last= Deletes the environment variable last. + +set Sws* Displays the values of all environment variables whose names start with sws. + + +Values are displayed inside square brackets. The list pauses when the screen is full. + + +3 WORKABOUT COMMAND PROCESSOR + + +Note that environment names and values are both case dependent. Thus the environment variables group +and Group would be distinct. + + +The value (and, indeed, the name) of an environment variable may contain binary data. When displaying +the content of an environment variable, non-printable byte values are displayed as or , for +example. There is, however, no mechanism for setting binary values from the Command Processor. + + +SETDEF Alter system settings + + +SETDEF [AMnn][ABnn][DDMY | DMDY | DYMD][KO | K1][S+ | S-][T12 | 124] + +Alter system settings, (which are otherwise set by menu options). + +The sETDEF command on its own does nothing - it must be followed by at least one parameter. +The allowed parameters are given below. + + +AMnn Auto-switchoff the machine after nn minutes of inactivity. Range 01 to 30. Values +outside this range will not give an error, but the setting will not be changed. + + +ABnn Auto-switchoff the backlight after nn minutes of use. Range 01 to 10. Values outside +this range will not give an error, but the setting will not be changed. + + +DDMY Date format DD/MM/YY. Note that the separator (/) can be changed via the menus. +DMDY Date format MM/DD/YY. + +DYMD Date format YY/MM/DD. + +Dn Set start of week to n, where 0 is Monday, | is Tuesday etc. + +KO Select standard keyboard. + +K1 Select special keyboard. + +S+ Sound on. + +s- Sound off. + +T12 Time format am-pm. Note that the separator (:) can be changed via the menus. +T24 Time format 24 hour. + +TS+ Summer time on. + +TS- Summer time off. + + +Sound settings for beeps and key clicks, zoom and text wrap on the screen are not configurable using +SETDEF. + + +The default machine settings are: +e Auto-switchoff the machine after 5 minutes of inactivity. +e Auto-switchoff the backlight after 10 minutes of use. +e Date format DD/MM/YY. +e =6The "start of week" default is Monday. +e Standard keyboard, (unless the machine has been factory-configured for the special keyboard). +e = All sound is on. +e Beeps are loud. +e = Key clicks are loud. +e¢ Time format am-pm. The separator is a colon (:). + + +e Summer time off. + + +WORKABOUT PROGRAMMERS REFERENCE + + +e Zoom is on setting 3 (see table for zoom settings in the Font sizes and zoom settings subsection +earlier in this chapter). + + +e Wrap is off. + + +SHEET Run the spreadsheet application Sh3 + + +[START] {SHEET | SH3} [system::] [drive:] [path] [filename[.extension] ] +Runs the spreadsheet application Sh3. Sheet is an alias for Sh3. +If preceded by start, Sh3 will be run asynchronously. + + +If no file specification is provided, and the current drive is m-:, (and sheet.spr does not already exist), a +dialog is presented asking: + + +Create "M:\SPR\SHEET.SPR"? +Otherwise, if sheet.spr does already exist, then it will be presented directly for editing. + + +If any system, drive or path is provided, but no filename, the sheet.spr file will be placed in, (or retrieved +from), the specified location. The default directory is \spr\, and it is recommended that this is where all +spreadsheet files are kept. + + +If a filename is given, a .spr file of that name will be created (as above) and/or presented for editing +depending on whether it currently exists or not. + + +An extension to the filename may be provided that differs from .spr, but this is not recommended, since it +would make identification of the file type difficult. + + +Notes: +Help on using the Spreadsheet application is available by pressing Shift-Esc. + + +For further information on using the Spreadsheet application, see the Workabout User Guide. + + +SHIFT Shift batch file parameters + + +SHIFT procname + + +Shift the replaceable parameters of a batch file one position to the left. Thus 1 becomes s0, 9 becomes 8 +etc. + + +The command su1Ft alters the values of the replaceable parameters s0 to 9 inclusive by copying each +parameter into the one prior to it. Thus the value of s1 is copied to 0, the value of s2 is copied to $1, and +so on. This can be used to help write a batch file that does the same operation on an unspecified number of +parameters. + + +The su1rt command can also be used to construct a batch file that will accept more than 9 parameters (in +addition to the name of the executable). If more than 9 such parameters are specified on the command +line, those that appear after the ninth (<9) can be moved one at a time into s9 by repeated use of sHIFT. + + +There is no reverse sHirT command. Once the sHirt command has been carried out, the value of 30 that +existed before the shift is not recoverable. + + +The following batch file, pstpzL.BtTF, shows how to use the sHirT command with any number of +parameters. It deletes a list of files from a specific directory. The parameters are the directory name +followed by any number of filenames. + + +3 WORKABOUT COMMAND PROCESSOR + + +ECHO off + +REM PSIDEL.BTF deletes any number of files from a given directory. +REM The command uses the following syntax: psidel dir filel file2 +SET fromdir=%1 + +:getfile + +SHIFT + +IF "S$1"=="" GOTO end + +DEL %fromdir%\%1 /y + +GOTO getfile + +send + +SET fromdir= + +ECHO All done + + +START Start a process asynchronously + + +START procname +Launch the given process and return immediately. +Starts the first process found matching the specification in procname, (asynchronously). + + +Notes: + +For a process that is an alias of another program, using start will start a process that appears to LsEe or +LDEV as an instance of the base process. For example: all text and program editors are aliases of the Word +application. Using start Ep1T will start an instance of Word. It will thus appear in an LPRoc or LSEG +listing as an instance of Word. Using worp or sTarT worp is banned artificially. + + +On the other hand, start sHEET will start an instance of the Sh3 application. Be aware that a process +started with sH3 or START SH3 cannot, however, be stopped with stop sHEET. The user-visible name Sheet +is only used to start an instance of the sh3.img program running. + + +STOP Stop a process +STOP procname [/y] + +Terminate the named process or processes matching the specification in procname. + +Processes are sent a termination message. + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + + +To stop a specified instance of a number of running tasks, all with the same name, the exact process name +must be found out and used. For example: stop job.$09 OF stop job.$14. + + +For most applications, the effect of being stopped is identical to being killed, (see the kx1LL command). The +application is interrupted immediately, with no chance being provided for data to be saved to file or to +environment variables. However, an application can make use of the PLIB function p_onterminate to +elect to receive an inter-process message instead of being summarily terminated. For further details, see +the descriptions of p_pterminate and p_onterminate in the Error Handling chapter of the PLIB +Reference manual. + + +Notes: + +The stop command is designed for use with user-developed programs during the development process. +Fully developed (and built-in Psion) applications would normally be stopped using the options available +from their menus or from the System Screen. + + +TIME Display current time + + +Display the current time, in the default format, or the format specified by the most recent szETDEF or menu +command. + + +The default display format is: + + +hh:mm:ss [am|pm] + + +WORKABOUT PROGRAMMERS REFERENCE + + +For example 09:30:15am will be displayed if the current system time is fifteen seconds after half past nine +in the morning. + + +Use the Time and Date option on the Time menu to change the time. +Use the setpEF command or the Formats option of the Time menu to change the format in which the time + + +is displayed. + + +TYPE Type a text file +TYPE filename +Print a text or batch file to the screen. + + +The display pauses itself automatically after each screen full of text. + + +VER Display software version numbers + + +VER + + +Display the Workabout ROM version number, the date and time that the ROM was mastered, the (EPOC) +Operating System version number, the Shell version number and the (Text) System Interface version +number. + + +VOL Display the disk volume label etc +VOL [drive:] +Display information about the disk volume on the current or specified drive. + + +This information includes the volume label, media type, free space in bytes and the total space in bytes. +For RAM SSDs, the battery state is also given. + + +To change the volume name use the LaBEL command. The label on a volume may also be changed when +the volume is formatted using the rormat command. + + +WAIT Wait for a process to terminate +WAIT [procname] +Suspend the Command Processor until the (named) process terminates. +If a process name procname is supplied, the message: +Waiting for "procname" + + +is displayed and the Command Processor becomes non-interactive until such time as another process +terminates. + + +If no process name is given "any process" 1s substituted for "procname" and (for example) the message: +Waiting for "any process" + +is displayed. + +To break out of this mode, press PSION+ESC. A Yes/No dialog is displayed, headed: +Stop waiting for "procname" + +If n is pressed then a notifier stating: +Waiting for "procname" + + +is displayed, but if y is pressed then the waiting stops. + + +3 WORKABOUT COMMAND PROCESSOR + + +Commonly, this command will be used inside batch files in the following general pattern: + + + + + + +wait + + +Example: + + +START MYSERVER + +IF ERRORLEVEL QUIT + +START MY_APP + +IF NOT ERRORLEVEL WAIT MY_APP +KILL MYSERVER /Y + + +Notes: + +The nproc and nsec commands can be used to determine what processes are running. wart will only wait +for processes started by the Command Processor (unlike stop and xru1 which hit anything with a +matching name). Neither the proc nor the sec command can be used to determine how a process was +started. + + +For a process that is an alias of another program, using WAIT basename will wait for a process that appears +tO LSEG Or LDEV as an instance of the base process (basename). For example: all text and program editors +are aliases of the Word application. Using wart epit will wait for an instance of Word. Using wart worp +is banned artificially. + + +In contrast, WAIT SHEET can be used to wait for the termination of an instance of the Sh3 application that +was started with sHEET or START SHEET. Be aware that a process started with sH3 or START SH3 cannot, +however, be waited for with wAIT SHEET: you must Use WAIT SH3 instead. + + +WORKABOUT PROGRAMMERS REFERENCE + + +APPENDIX A + + +TECHNICAL SPECIFICATIONS + + +Psion Workabout Technical Specification + + +Physical characteristics + + +Size +Weight + + +Screen + + +Sound + + +Power supply + + +Internal +Backup + + +External + + +Memory + + +Built in + + +System information + + +Processor +Operating system + + +Communications + + +Protocols: + + +Language + + +180mm x 90mm x 35mm. +325g (including battery pack). + + +Backlit (optional). + +240 x 100 pixel LCD. + +Size 62.4mm x 30mm (2.45" x 1.18"). +Pixel pitch 0.30mm x 0.26mm + +Pixel size 0.27mm x 0.23mm. + + +Piezo buzzer. + + +Nickel-Cadmium rechargeable battery pack, or 2 x AA alkaline batteries. +3V Lithium CR1620 battery. + + +A Series 3 mains adaptor can be used in conjunction with the LIF Converter unit +for main power supply and trickle charging, (see Expansion below). +Vehicle power adaptor (24v & 12v cigarette lighter sockets), from Jan/Feb 1997. + + +Psion Workabout Docking Station. + + +1MB Masked ROM (for OS) and 256KB RAM or IMB RAM. +Two SSD drives allow extra storage space on Flash/RAM SSDs, up to 8MB. + + +NEC V30 running at 7.68MHz. +EPOC. + + +XMODEM, YMODEM (and ZMODEM, except 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. + + +WORKABOUT PROGRAMMING GUIDE + + +Expansion + + +Internal + + +External + + +Peripherals + + +Environment + + +Operating temperatures +Storage temperatures +Operating humidity +EMC + +Safety + +Drop + +Other + + +Serial Numbers + + +One internal expansion card can be installed. + +Currently an RS232/RS232 TTL serial interface and an RS232/barcode +reader interface expansion module are available. These must be factory +fitted. + + +A combined external power supply connector and fast serial link connector +LIF Converter unit is available. This plugs into the standard LIF socket + + +External peripherals (such as a modems, printers or barcode readers) can be +plugged into any suitable socket (where fitted). + + +-20°C to 60°C.. + +-25°C to 80°C. + +0% to 90% non-condensing. + +FCC Part 15 Class B; CE Mark, E-Mark +EN60950 + +1m onto concrete on any face + +IP54 (dust proof & splash proof; some models). + + +The following numbering system has been devised to cover all variants of Workabout. The code is 10 + + +Digit Alphanumeric: + + +G_a_B_5_XX_xxxx + + +G denotes that the product is a Workabout + + +© can be A to Z and denotes the body colour and expansion variant: + + +Letter Body +Grey +Grey +Grey +Yellow +Yellow + + +F Yellow + + +moaw p> + + +Variant + +Normal + +TTL + RS232 +Barcode + RS232 +Normal + +TTL + RS232 +Barcode + RS232 + + +B can be A to Z and denotes memory configuration: + + +5 can be 1 to 9 and denotes year of manufacture: + + +Letter Memory +A 256KB +B 512KB +C 1MB +D 2MB +Digit Year + +1 1993 +2 1994 +3 1995 +4 1996 +5 1997 + + +A-2 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +X can be 01 to 52 and denote the Week of manufacture: +Digits Week + +Ol Starts first of Year at Monday 7a.m. + +52 Last Week of December + + +XXxx can be 0000 to 9999 and is the unique numeric identifier for each PCB built in a week, giving +10,000 permutations each week. + + +Serial numbers prior to GXCXX310NM + + +The RS232 port on both Barcode and TTL options uses a Maxim chip to perform the RS232 level +conversion. This chip has a power saving feature which means that it will only power up when it detects +RS232 signal levels on any of the inputs. This can cause a problem interfacing to devices which also +incorporate the same Maxim chip, since neither device will power up. The Ericsson Mobidem +incorporates this device and therefore earlier models of the Workabout had difficulty communicating with +a Mobidem. A modification to the Barcode and TTL PCBs, disabling the power save feature, was +introduced into production from serial number GXCXX310NM onwards. + + +Psion Workabout RS232 / RS232 TTL Interface Module +- Technical Specification + + +This peripheral module provides: +e =An RS232 (IBM PC/AT type) interface at 12V (EIA-232) levels. Connector: 9 way D-type male. + + +e A TTL level RS232 interface at 5V CMOS levels together with a 5V power output at up to 200mA +current drive capability. Connector: 9 way D-type female. + + +The board can be operated at up to 19,200 Baud rate. + + +The physical arrangement of the board and connectors inside the Workabout is shown below: +RS232 RS232 + + +(0to5V) — (4/- 12v) + + +Torson 26 way connector +(connects the main board to +the peripheral module) + + +Flexi cable + + +26 way flexi connector + + +View from the front of the machine + + +RS232 (AT) Cradle +(+/-12v) (Connector) + + +or RS232 TTL + + +Remarks: + + +e = =The Workabout can communicate to the RS232 interface or the RS232 TTL interface, but cannot talk +to both at the same time. + + +e The connectors at the top of the machine are in the default positions. +- The D-type connector for RS232 may be fitted at the bottom, if required. +The bottom RS232 connector and the top RS232 connector cannot both be fitted. +- The D-type connector for RS232 TTL may be fitted at the bottom, if required. +The bottom RS232 TTL connector and the top RS232 TTL connector cannot both be fitted. + + +A-3 + + +WORKABOUT PROGRAMMING GUIDE + + +e The various input and output signals of the connectors are shown in the table below. + + +Pin number RS232 TTL interface RS232 interface +VCCEXT + + +n. +RX +T +G +D +R +C + + +4 +il, +an u + + +Q)A + + +nf + + +Note: Under normal conditions the signal levels into the TTL port should not exceed 5.5V DC. +Connected devices should be designed or specified to guarantee this is not exceeded. Under fault or +transient conditions 6V DC should not be exceeded. + + +Ic +x +ND +SR +TS +TS +Ic + + +al +1 +2 +3 +4 +5 +6 +a) +8 +9 + + +Psion Workabout RS232 / Barcode Interface Module +- Technical Specification + + +This peripheral module provides: +e An RS232 (IBM PC/AT type) interface at 12V levels. Connector: 9 way D-type male. + + +e A barcode wand interface, together with a 5V power output with up to 200mA current drive +capability. Connector: 9 way D-type male (with click lock when mounted at the top of the +machine, without click lock when mounted at the bottom) + + +A Hewlett Packard microcontroller HBCR-1612 is used to read and decode the barcode external input, and +then transmit the data as RS232 signals at up to 9,600 Baud. + + +The physical arrangement of the board and connectors inside the Workabout is shown below: + + +BAR CODE +CLICKLOCK RS232 + + +Torson 26 way connector +(connects the main board to +the peripheral module) + + +Flexi cable + + +26 way flexi connector + + +View from the front of the machine + + +BAR CODE Cradle +or RS232 (Connector) + + +Remarks: + + +e = =The Workabout can communicate to the RS232 interface or the barcode interface, but cannot talk to +both at the same time. + + +e The connectors at the top of the machine are in the default positions. + +- The barcode connector may be fitted at the bottom, if required. The bottom barcode connector +and the top barcode connector cannot both be fitted. + +- The RS232 connector may be fitted at the bottom, if required. The bottom RS232 connector and +the top RS232 connector cannot both be fitted. + + +A-4 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +e = The various input and output signals of the connectors are shown in the table below: + + +RSID eric +1 + + +Ic + + +0 mAOANI NN BW WN + + +Conversion of an HC barcode reader for Workabout connection + + +The details of the wiring changes needed to change the connector on a barcode reader from a six pin +minidin for an HC to a 9 way D type for a Workabout are given below. These are the wires coming from +the barcode reader itself to the connector that plugged into the HC. + + +The wires connected to the six way minidin pins as below left need to be reconnected to the 9 way D type +pins as below right. The signal directions given are from the HC/Workabout point of view. + + +New 9 way D ype +DSR input + +[2 [enable ———SS—~ utp 6 DTRSSCSCS~S utp | +Ps [switch ————~‘finput_[ | noteonnested ———S—~sSCSC* + + +TXD (barcode data) TXD (barcode data) + + +VCCEXT (barcode power supply) | output | 9 VCCEXT (barcode power supply) +-6_| GND (ground) [ [Tor 8 [GND Ground) | + + +Important notes + + +The software control for pin 2 on the old 6 way connector was never implemented, therefore extra +program code may be required to implement the DTR function on the equivalent pin 6 in the new 9 way +connector. + + +Some barcode readers do not have all of the pins on the 6 way connected to anything, and some have +wires that are not connected to any of the pins in the connector. Only make existing connections as above. +Any wires or pins unconnected should remain unconnected in the 9 way connector. + + +Workabout Vehicle Interface Cradle (VIC) +- Technical Specification + + +The Workabout Vehicle Interface Cradle (WVIC) is a peripheral for the Workabout that provides extra +RS232 communications facilities for the Workabout, as well as being capable of providing both operating +power and internal Ni-Cd battery charging current when supplied from either the main vehicle supply (at ++12V) or an auxiliary 10V regulated supply (via the Extended 15-way RS232 port). The interface between +the Workabout and the Cradle is through the standard Psion LIF connector in the base of the Workabout. +The Workabout is held in place by the standard holster. The WVIC may be dashboard mounted with an +optional mounting bracket which allows the unit to be angled for ease of use. + + +Physical & Environmental + + +Weight: 317g + +Size: 140mm (H) x 92mm (W) x 62mm (D) +Temperature Range: Operation: 0° C to 50° C + +EMC EN5022, E marked + + +Serial Communications + + +The RS232 serial ports (one or three depending on variant) allow connection to a wide range of devices +such as radio modem, GPS unit, printer, or input from vehicle information/management systems. +Simultaneous connection to several such devices is possible with the three port variant. + + +WORKABOUT PROGRAMMING GUIDE + + +Build options + + +Two build options are available as standard products with either one or three RS232 ports and vehicle +power input. The D-type connectors have screw locks. A total of four build variants are available: + + +Vehicle Cradle build variants + + +Number of Ports 12V vehicle power connector | Regulated 10V input via 15 way D type + + +TRS232 Por (Sway Dyps) [| Cd CS +3 RS232 Ports (1 x 15 way +D-type, 2 x 9 way D-type) + + +Note that the 10V power input versions must be built to order. + + +Power supply + + +Note that the unit accepts a 12v DC vehicle supply, and is not suitable for connection to 24v. In the case of +a 24v or 36v vehicle, the power to the unit has to be taken from the vehicle’s 12v rail, or a suitable +DC/DC convertor or dropper/regulator has to be used. + + +The WVIC supplies enough current to charge a NiCd battery pack and run everything on the Workabout +simultaneously, e.g. writing SSDs, backlight, powering port devices. The Workabout will not start +draining the batteries as well as using power from the WVIC provided the supply is at least 11v DC. + + +Current consumption figures for a 3 port 12V WVIC are as follows (all figs in mA): + + +WVIC only a ee +WVIC + Workabout (off), no batteries Ca Ea +WVIC + Workabout (off) + rechargeable pack + + +WVIC + Workabout (on) + rechargeable pack a dependent +as above with VIC ports enabled and unloaded + + +as above with ports all loaded 170 7 aoe on what is +connected + + +Additional current for backlight 50 + + +For peripherals connected to the Workabout, current consumption will depend on what the peripheral is. + + +For a 10OV DC powered WVIC, 10mA should be deducted from the typical values, and 15mA should be +deducted from the maximum values. + + +3 port and vehicle power input option + +This variant of the WVIC (Psion part number 2800-0024) incorporates the following features:- +e Power input from the vehicle +e Surge suppression and regulation of the vehicle 12v supply to 10v DC + + +e Vehicle ignition switch sensing for Workabout wake up. Power down of the Workabout is +available under application control. + + +¢ Conversion of Psion Fast Serial to RS232 +e = Trickle charge of the Workabout Ni-Cd rechargeable battery pack +e 2RS232 ports - 9 way D-type with screw locks; 1 RS232 port - 15 way D-type with screw locks + + +A-6 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +Port F + + +1 port and vehicle power option + + +This variant of the WVIC (Psion part number 2800-0028) incorporates the following features:- + + +Power input from the vehicle +Surge suppression and regulation of the vehicle 12v supply to 10v DC + + +Vehicle ignition switch sensing for Workabout wake up. Power down of the Workabout is +available under application control. + + +Conversion of Psion Fast Serial to RS232 +Trickle charge of the Workabout Ni-Cd rechargeable battery pack pack +1 RS232 port - 15 way D-type with screw locks + + +WORKABOUT PROGRAMMING GUIDE + + +Mounting bracket + + +A mounting bracket (Psion Part number 2400-0082) is available for mounting both options of the Vehicle +Cradle. + + +Vehicle power input connector + + +ee Connector housing + + +Pie Pin 3, vehicle -ve, ground + + +*.__ Pin 2, vehicle ignition signal, 12v dc + + +Pin 1, vehicle +ve, 12v de / + + +Vehicle power in + + +Switched 12V in + + +The function of each pin is: + + +1. Main 12V DC input from the vehicle power supply is internally surge suppressed, and +regulated to provide a 10V rail which then powers the Workabout connected to the LIF. This +10V rail is also used to drive a constant current source which supplies 83mA (nom.) to the +BAT connection of the Workabout LIF socket, and hence to the internal Ni-Cd pack in a +Workabout. + + +2. Switched 12V in is used to provide a wake-up signal to the Workabout. When this signal +goes high, the Workabout will receive a high level on its EXON line in the LIF connector. +This connection is optional - see Extended 15-way RS232 serial port details. + + +3. GND is the main ground return line for the vehicle power supply. + + +A-8 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +Conventional 9-pin RS232 serial ports + + +The unit has two 9-way D-type connectors (female), which provide the same RS232 signals to the outside +worlds as are normally found on the RS232 connector of a Workabout RS232 expansion interface, with +the addition of a further pin, described below. The connections are: + + +9 RI (but see below) + + +The RI function is not directly supported by the serial port drivers on the Workabout; the state of the RI +line can be read by the serial port driver on bit PA4 of the ASICS. + + +These ports are accessed by the Workabout as standard serial devices, and are referred to as ports I and F. +Port F is the closest of the two to the top of the unit when installed, and port I is that closest to the end of +the unit holding the Workabout LIF connector. + + +Extended 15-way RS232 serial port + + +The unit has a further 15-way D-type connector at its bottom edge (adjacent to the 12V vehicle power +connector). This provides the same functionality as the other two RS232 connectors (addressed as port C), +as well as some extended functions, which are described below. The connections are: + + +a 0) + +oO +2S RX ata) ——OSC—~—SCSCSSC—C~—~—sRTS CSCS +Ps S*d TX (data out) SCS SSCS TSS + + +fa SSOSCSCSCSCCCS YR see Below ——SSSSC~*S +ro] External WakeUp Gee below) [14.—S*(NCSOCSCS—S—SCS + + +The RI function is not directly supported by the serial port drivers on the Workabout; the state of the RI +line can be read by the serial port driver on bit PA4 of the ASICS. + + +Pin 6, External WakeUp, is internally connected to pin 2 of the external 12V power connector, and can be +used in the same manner to cause the Workabout to turn on when a voltage is presented on this pin. It can +also be wired, in the users cable, to pin 8 (the DSR line) to provide a wake-up on reception of a DSR +signal - this is the normal arrangement for Psion products with external wake-up signals. It follows that a +connection from pin 6 to pin 8 should not be made at the same time as a connection to pin 2 of the +external 12V input connector- this would result in the Workabout receiving wake up events at the wrong +time, and could result in damage to the equipment connected to this port (though not to the VIC itself). + + +Vin expects a 250mA, 10V, 10% regulated positive DC voltage , and can be used to power the VIC and +Workabout, as well as supplying charging current to the internal Ni-Cd pack. Internal circuitry allows for +both this supply and the 12V vehicle supply to be present at the same time, although only one of them is +necessary. + + +Psion LIF Connector + + +The Psion LIF connector details are covered in Appendix A - Technical Specifications of the HC +Programmers Reference manual. + + +A-9 + + +WORKABOUT PROGRAMMING GUIDE + + +Psion Workabout Docking Station +- Technical Specification + + +Introduction + + +The Workabout Docking Station is designed to provide a multi-function mounting point for the Psion +Workabout corporate hand held computer, (referred to in this technical specification as the computer). + + +The Docking Station has the following features: +e Battery management, including fast charge of batteries (fast model) +e Small footprint +e Reliable connection between the Psion and the docking station using the LIF connector +e¢ Option for in-vehicle use + + +e FCC, static and safety approval + + +Variants +A total of four build options available: +1. Workabout fast charge +2. Workabout trickle charge +Note: Both the above variants are also available with vehicle support circuitry on board. + + +This gives a total of 4 possible build variants. + + +Identification +PCB number and revision marked on PCB is common for all variants. +The main visual differences that distinguish The Workabout fast charger from the HC fast charger are: + + +Workabout fast charger: 2 pin 1.3mm DC jack fitted +HC fast charger: 4 pin bulky power supply socket fitted + + +Docking Station Unit + +Main features + +The Docking Station Unit has the following features: +e Fast charging of the computer internal battery pack, (fast model). +e Spare battery pack fast charging. +e Stable desktop mounting. + + +e Accepts some of the HC expansion modules which communicate via the Psion Fast Serial (PFS) +protocol. These are accessible by any Workabout computer inserted into the Docking Station. See +the table Psion HC build variant and accessories matrix at the end of Appendix A - Technical +Specifications in the HC Programmers Reference manual for details. + + +e Data transfer from the computer, (with the appropriate expansion module and software driver). +e Simultaneous battery charging and data transfer, (if the Psion is not monitoring battery status). +e Wall mounting and bulk head fitting designed in. + + +e The battery compartment is factory configured to accept as standard the Workabout rechargeable +battery pack. + + +A-10 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +Status indicators +There are several LEDs on the front of the charger unit to indicate the following: +e¢ Communications/data transfer +e §=© Yellow during data transfer +e Power status-On/Off +¢ Green when charger is connected to mains power +e¢ Main computer battery charging status (Fast model only, see Battery Status LED conditions) +e Spare battery charging status (Fast model only, see Battery Status LED conditions) +Battery charging +The Docking Station has two charging modes: +e = Normal + + +e Software controlled. See the Cradle and Docking Station chapter in the I/O Devices Reference +manual. + + +If both the computer and the spare battery are fitted when the docking station is connected to mains +power, charging priority will go to the spare battery. If the docking station is already connected to mains +power , charging priority will go to whichever battery was plugged in first. + + +The computer main battery can be discharged before charging commences. This feature is controlled from +the computer. + + +Note that the Slow Charge variant of the Docking station does not have a Battery Status LED. This is +because it has only one status - charging. + + +Battery Status LED conditions + + +LED indication Battery status + + +Flashing red Preparation for fast charging (two seconds) or +Battery condition outside specified range - trickle charging or + + +For the battery pack inside the Psion: discharging under software +control or + + +Error + + +Steady red Charging +Steady green Charged + + +Flashing red/green Waiting or + + +For the battery pack inside the Psion: discharging under software +control, while the spare is fast charging + + +Charging both battery packs + + +If a spare battery is inserted into the Docking Station whilst a battery pack inside the Psion is being +charged, charging of the spare pack will begin after the internal battery pack has been charged. + + +If a Psion computer is inserted into the Docking Station whilst a spare battery pack is being charged, +charging of the battery inside the Psion will begin after the spare pack has been charged. + + +If both the Psion and the spare battery pack are inserted into the Docking Station at the same time, (or +both are in the Docking Station prior to it being connected to the mains), the packs will not be charged +simultaneously. In the case of the Fast Charge variant of the Docking Station their respective LEDs will +flash red for about two seconds, until the charger decides which to battery pack to charge. The LED for +the one charging then comes on red, and the other one's LED starts flashing red/green as it is waiting to +be charged. For both Docking station variants the spare battery pack will normally be charged first. + + +A-11 + + +WORKABOUT PROGRAMMING GUIDE + + +Battery Fast Charging conditions + +The Fast Charge variant of the Docking Station can Fast Charge in the following conditions: +Within the temperature range: 5 to 45 °C + +Voltage of the battery pack: 1.8 to 3.8V DC for the Workabout. + + +If the battery pack temperature or voltage is outside the specified range, the charger trickle charges until +the condition is within the allowable range, after which it will fast charge. A new or fully discharged +battery pack (that has been left on for a long time) may have a voltage below the minimum for Fast +Charging. + + +If the battery temperature is within the allowable range and the battery status LED continues to flash red it +is likely that the battery pack is faulty. + + +Discharging prior to charging & capacity measurement + + +The Psion's internal battery pack may be discharged, under software control, prior to charging. This is not +possible with the spare battery pack. + + +It is possible to charge the spare battery pack whilst discharging the main battery pack in the Psion. + + +Software controlled discharging of the battery pack leaves the voltage above the allowable minimum for +subsequent Fast Charging. + + +Charging will automatically commence after the battery is discharged. + + +Under software control it is also possible to measure the actual capacity or the remaining capacity of the +battery pack inside the Psion computer. The discharging current for the Workabout charger is +290mA + 5%. + + +Fast Charging times + + +A fully discharged battery pack takes approximately one hour to Fast Charge to 90-95% of its maximum +capacity. If left in the Docking Station after this time it will be "topped-up" to its maximum capacity after +a further two hours. + + +Slow Charging times + + +A fully discharged battery pack takes approximately 14 to 16 hours to Slow Charge to 100% of its +maximum capacity. + + +Charging limitations + + +The Fast Charge and Slow Charge facilities only support the main Computer battery, not the battery of +any attached peripheral. The HC Printer however, contains its own Quick Charge circuitry and may +charge simultaneously under software control. + + +LIF Mounting Kit + + +The LIF mounting kit allows a LIF connector on the end of a cable to be fitted to a holster. + + +The holster itself is a plastic moulding into which the computer can be inserted. This incorporates a +positive latching mechanism which holds the computer securely in place. The holster does not include any +electronics. + + +The Clip cover and the 2 short screws that are fitted as standard to the LIF connector will need to be +replaced with the blank cover and the 2 long screws supplied with the kit. + + +Workabout Holster with Socket Housing + + +The kit for the Workabout Computer consists of:- +e HC holster + +e LIF connector support + +e LiF connector blank front cover + + +e 2screws - type K2.2 x 12 mm CSK ( not shown) + + +A-12 + + +APPENDIX A: TECHNICAL SPECIFICATIONS + + +Workabout Docking Station + + +This is a Fast Charger with serial data communication capabilities supplied with a factory fitted +Workabout holster, also known as a Workabout Docking Station. The cable from the hardware board to +the LIF connector is protected by an over-moulded rubber grommet. + + +A 12v 1 amp unregulated power supply is supplied with the docking station. + + +Workabout Docking Station : UK Part +Number 1801-0001-01 + + +Note: Euro part number 1801-0004-01, US part +number 1801-0005-01 + + +12V 1 amp unregulated Power Supply : UK Part Number 2300-0197-01 +TL + + +— + + +~ ~S + + +Note: Euro part number 2300-0210-01, US part number 2300-0211-01 + + +A-13 + + +APPENDIX B + + +DIFFERENCES BETWEEN +THE HC COMMAND PROCESSOR, +THE WORKABOUT COMMAND PROCESSOR + + +AND MS-DOS + + +Introduction +About this appendix + + +This appendix compares the Psion HC Command Processor commands with the commands of the +Workabout Command Processor and the MS-DOS Command Processor. It is provided for two purposes: + + +e So that developers may easily convert batch programs written for the Psion HC into batch +programs that will run on the Workabout. + + +e So that developers familiar with writing MS-DOS batch programs may easily find the similarities +and differences relating to writing batch programs for the Psion HC and the Workabout. + + +It is not the purpose of this appendix to give the full syntax of MS-DOS commands, and may be +used to indicate an incomplete syntax statement, (refer to your MS-DOS manual or MS-DOS Help). +Furthermore MS-DOS is available in many versions. At the time of writing the current version was 6.2. +Commands that are only for use in MS-DOS config.sys files have not been included if they have no +relevance to Psion machines. + + +Help + + +Help about commands, (and other features of the machine), is not available from the system on the Psion +HC, but is on the Workabout. Help is also available in current versions of MS-DOS. + + +Commands + + +Shortened versions of commands are not available on the Workabout (or in MS-DOS). For example, com +is not an acceptable shortened form of commanp. The Workabout Command Processor thus differs from +the Psion HC Command Processor which does allow command abbreviations. Where the full length HC +command is longer than the Workabout command the extra HC characters are enclosed in braces, {}, in +the heading. Optional characters for an HC command are enclosed in square brackets, [], in the syntax +statement. + + +B-1 + + +WORKABOUT PROGRAMMING GUIDE + + +File and directory names + + +wom + + +Psion computers allow the use, for example, of the "+" character in filenames, which is not allowed in +MS-DOS, (see the copy command). + + +On the Workabout a trailing backslash can generally be used to clarify that a name is a directory rather +than a file, whereas on an HC, (as in DOS), a parsing error may occur. For example, if the current drive is +m: and the current directory is \img\ the command: + + +md tools\ + +will successfully create a directory on the Workabout, but not on the HC. + +In all, fully specified Psion filenames (£ilespec) are regarded as having five parts: +1. A filing system (e.g. loc:: or rem::). + +A drive or device (e.g. b:). + +A path (e.g. \ or \accounts\jan\). + +A filename (e.g. job). + + +Oi Ri ee, TS + + +An extension (e.g. .img). +In MS-DOS the file specification syntax \\server\ is analogous to the Psion filing system component. + + +Wildcards + + +The use of * differs from its use in DOS in that, on the HC and the Workabout, it is possible to use, for +example: + + +at bi ® + + +to select all files whose file name starts with a and ends with b. In DOS, a*b.* has the same effect as + + +ar. *. + + +Batch files + + +Batch files may only be run synchronously on the Workabout, (as in DOS), or on an HC. On the HC +preceding the name of the batch file by @ is required, but not on the Workabout. In Workabout batch files +@ suppresses echo, just like in DOS. + + +On the Workabout batch files must have the extension .btf, (just as DOS batch files must have the +extension .bat), but on the HC other extensions (though not advisable) are allowed. The Workabout stores +batch files, by default, in a \bif\ directory. The HC has no default directory for batch files, (neither do DOS +machines). + + +On the HC it is not possible to pass parameters to a batch file, but on the Workabout you can pass as many +parameters as will fit on the command line, (like DOS). Workabout batch files can also use IF...GOTO... +constructs, unlike HC batch files, (but like DOS ones). + + +Default directory structure + + +On the Workabout there is a fixed default directory structure, into which files with specific extensions are +placed. This directory structure is searched automatically for program files if full details are not provided +of path and filename extension. The HC does not have a default directory structure, (neither do DOS +machines). + + +Launching programs + + +The Workabout looks for filenames in the following order of extensions, if no extension is given: + + +1. .img +2. .app +3. .opo +4. .opa +5. .btf + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +The order of searching on the Workabout is described in detail in the chapter The Workabout Command +Processor. + + +The HC, on the other hand, looks for filenames in the following order of extensions, if no extension is +given: + + +1. .opo +2. .img +3. .app + + +The order of searching on the HC is described in detail in the chapter The HC Command Shell in the +HC Programmers Reference manual. + + +DOS machines do not have fixed search orders, and search paths must be specified using the paTH +command. + + +Memory resident programs + + +The Workabout (or any other Psion SIBO machine) can have programs running asynchronously in the +background, (see the HC Programmers Reference, Series 3 Programmers Reference and Workabout +Programmers Reference manuals). An example of this is the LINK program. In contrast MS-DOS has +Terminate and Stay Resident programs (TSRs) which are installed into memory (usually on boot up) but +cannot run until control is passed to them, (MS-DOS is not multi-tasking). + + +Alphabetical listing + + +APPEND Append directories to current data path + + +HC Command Processor +Not supported. +Workabout Command Processor + + +Applications each have their own preferred path for data files. See the Default location of files section of +the chapter The Workabout Command Processor in the Workabout Programmers Reference manual. + + +MS-DOS Command Processor + + +APPEND + + +Enables programs to open data files in specified directories as if the files were in the current directory. + + +ATTRIB{UTE} Set or clear file attributes + + +Note that the a flag on the Workabout or PC is exactly the same as the m flag on the Psion HC. + + +HC Command Processor + + +ATT[RIBUTE] [system::][drive:][path]filename.extension [+h|-h] [+s|-s] [+m|-m] [+r]-r] +Sets or resets the hidden (n), system (s), modified (m) and/or read-only (xr) attributes of a file. + +A filename must be given. If all four attributes are omitted nothing will happen. + +The command does not accept a wild card specification. + + +Workabout Command Processor + + +ATTRIB [system::][drive:] [path] [filename] [.extension] [+h|-h] [+s|-s] [+a]-a] [+r|-r] +Sets or resets the hidden (nh), system (s), archive (a) and/or read-only (r) attributes of a file. + + +If all four attributes are omitted, attrib displays the existing settings. +If the filename is also omitted then the attributes of all files in the current (or specified) path are +displayed. + + +The command does accept a wild card specification. + + +WORKABOUT PROGRAMMING GUIDE + + +MS-DOS Command Processor +ATTRIB [drive:][path]filename.extension [+h|-h] [+s|-s] [+a]-a]l [+r|-r] [/s] + + +Sets or resets the hidden (hn), system (s), archive (a) and/or read-only (r) attributes of a file. +The /s switch processes the current directory and all related subdirectories. + + +If all four attributes are omitted, attrib displays the existing settings. +If the filename and attributes are omitted then the attributes of the specified directory only are displayed. +If both path and filename are omitted the attributes of all files in the current directory are displayed. + + +The command does accept a wild card specification. + + +AUTO Set time to auto-switch-off +HC Command Processor +AUT[O] seconds + + +Sets the time for auto-switch-off. + + +Workabout Command Processor + + +Implemented via sETDEF. + + +MS-DOS Command Processor +Not supported. + + +BACKLIGHT Set backlight time-out +HC Command Processor + + +BACK[LIGHT] [time] + + +Sets the backlight auto-time-out to time, or if time is omitted, displays the current setting (in +hexadecimal). + + +Workabout Command Processor +Implemented via sETDEF, (or system interface menus). + + +MS-DOS Command Processor + + +Some screen savers provide similar functionality. + + +BACKUP Backup files + + +HC Command Processor + +Files are backed up to a PC using MCLINK, RCom or PsiWin. +Workabout Command Processor + +Files are backed up to a PC using MCLINK, RCom or PsiWin. +MS-DOS Command Processor + + +BACKUP +Backs up files from one disk to another, (MS-DOS versions 2.0 to 5.0). + + +BATCHK Start battery check program +HC Command Processor +BATCHK interval + + +Starts the program rom::batchk (if found), which monitors the voltages of the main and backup batteries. + + +Workabout Command Processor +Replaced by Shift-Ctrl-B. + + +MS-DOS Command Processor +Not supported. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +BATTERY Specify battery type + + +HC Command Processor + +BAT[TERY] type + +Specifies which type of main battery is installed. +Workabout Command Processor +Replaced by Shift-Ctrl-B. + +MS-DOS Command Processor + +Not supported. + + +BREAK Control extended CTRL-C checking + + +HC Command Processor + +Not supported. This is not relevant to Psion machines. +Workabout Command Processor + +Not supported. This is not relevant to Psion machines. +MS-DOS Command Processor + + +BREAK [ON|OFF] + + +Sets or clears extended CTRL-C checking. + + +CALC Run the calculator application +External command. + +HC Command Processor + +Not supported. + +Workabout Command Processor + +[START] CALC + +Run the Calculator application, Calc. + +MS-DOS Command Processor + + +Not supported, although calculator programs are available. + + +CALL Call a batch file from inside another batch file + + +Call a batch file from inside another batch file. + +HC Command Processor + +No command is required. The filename prefixed with an @, is all that is needed. +@[system::] [drive:] [path]batchfile[.extension] + +Psion HC batch files always return to any calling batch file on completion. +Workabout Command Processor + +[CALL ] [system::][drive:][path]batchfile[.extension] [batch-parameters] + + +Omitting the caLL command and Just using the file specification "chains" the named batch file, and it then +does not return to the calling batch file on completion. + + +MS-DOS Command Processor +[CALL ] [drive:][path]batchfile [batch-parameters] + + +Omitting the caLL command and Just using the file specification "chains" the named batch file, and +control then does not return to the calling batch file on completion. + + +WORKABOUT PROGRAMMING GUIDE + + +CD Display or alter current directory + + +Changes to a different path, or (if path is omitted) displays the current path. This is exactly the same as +CHDIR. + + +HC Command Processor + +CD [drive:] [path] + +Use cb [drive:]\ to change to the root directory of a drive. + +The HC maintains one machine-wide path. + +Workabout Command Processor + +CD [drive:] [path] + +Use cb [drive:]\ to change to the root directory of a drive. + +The Workabout maintains one path per local drive, plus a "current drive". To change drive use: +drive: + +MS-DOS Command Processor + +CD [drive:] [path] or + +CD [..] to change to the parent directory + +Use cb [drive:]\ to change to the root directory of a drive. + +MS-DOS maintains one path per drive, plus a "current drive". To change drive use: + + +drive: + + +CHCP Display or change character set + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +Psion-K can be used to switch the character set available from the keyboard. +MS-DOS Command Processor + +CHCP [nnn] + + +Displays or changes the active character set. + + +CHDIR Display or alter current directory + + +Changes to a different path, or (if path is omitted) displays the current path. This is exactly the same as +CD. + + +HC Command Processor + +The cp command is used instead. + +Workabout Command Processor + +CHDIR [drive:] [path] + +Use cHDIR [drive:]\ to change to the root directory of a drive. + +The Workabout maintains one path per local drive, plus a "current drive". To change drive use: +drive: + +MS-DOS Command Processor + +CHDIR [drive:][path] or + +CHDIR [..] to change to the parent directory + +Use cHDIR [drive:]\ to change to the root directory of a drive. + +MS-DOS maintains one path per drive, plus a "current drive". To change drive use: + + +drive: + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +CHKDSK Check or fix disk + + +HC Command Processor +This is not relevant to HC machines. +Workabout Command Processor + + +The "Disk info" option of the "Info" menu in the System Screen gives information such as: the disk's +label, its capacity, the amount of used space and the amount of free space. The vo, command also returns +this information. + + +MS-DOS Command Processor + + +CHKDSK + + +Checks and displays disk status, or may be used to fix a disk. + + +CHOICE Prompt user for choice +HC Command Processor + +Not supported. + +Workabout Command Processor + +Not supported. + +MS-DOS Command Processor + + +CHOICE + + +Prompts the user to make a choice in batch programs. MS-DOS 6.0 onwards. + + +CLS Clear the screen + + +Clears the screen, leaving the > prompt and cursor in the top left corner. +HC Command Processor + +Not supported. + +Workabout Command Processor + +CLS + + +MS-DOS Command Processor + + +CLS + + +COMMAND Start another command processor instance +HC Command Processor + +Not supported. See the HC Programmers Reference manual. + +Workabout Command Processor + +Not required, because the Command Processor can start many processes asynchronously. + +MS-DOS Command Processor + +COMMAND + + +Starts another instance of the command processor (shell). + + +WORKABOUT PROGRAMMING GUIDE + + +COMMS Run the communications application + + +External command. + +HC Command Processor + +Not available. + +Workabout Command Processor + +[START] COMMS [system::] [drive:] [path] [filename[.extension] ] +Run the communications application, Comms. + +MS-DOS Command Processor + + +The INTERLNK command does similar things, as do many other proprietary programs. + + +COMP Compare two files +HC Command Processor + +Not available. + +Workabout Command Processor + +Not available. + +MS-DOS Command Processor + +COMP + + +Compares two files and lists the differences between them. External command, up to MS-DOS 5, (c.f. rc +in MS-DOS 6 onwards). + + +CONFIG Set language file + + +HC Command Processor + +CON[FIG] filename + +Changes the language data file to that specified. If £i1ename is omitted, the effect is to revert to the file +sys$ctry.cfo. + +Workabout Command Processor + +Implemented via the seTtpEr command, (or the system interface menus). + +MS-DOS Command Processor + + +Not supported. The country command in config.sys does similar things. + + +COPY Copy file(s) + + +Copies one or more files, possibly changing their names in the process. +HC Command Processor +COP[Y] source destination + + +The source and dest ination file specifications can consist of a system and double colon, drive letter and +colon, a directory name, a filename, or a combination of these. + + +Several files cannot be combined into one file by using wildcards. +Workabout Command Processor +COPY source destination [/s] [/y] + + +The source and dest ination file specifications can consist of a system and double colon, drive letter and +colon, a directory name, a filename, or a combination of these. + + +The /s switch allows copying of subdirectories. +The /y switch allows overwriting without confirmation, (as in MS-DOS 6.xx). + + +Several files cannot be combined into one file by using wildcards. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MS-DOS Command Processor + + +coPY [/Y|/-¥Y] [/A|/B] source [/A|/B] [+ source [/A|/B] [+...]][destination [/A|/B]] [/V] + + +The source and dest ination file specifications can consist of a drive letter and colon, a directory name, a +filename, or a combination of these. + + +By using wildcards or the [+ source [/A|/B] [+...]] Syntax, several files can be combined into one +file. + + +COUNTRY Set country + + +HC Command Processor + +Not supported. The conric command does similar things. +Workabout Command Processor + +Not supported. The setpEF command sets which language file to use. +MS-DOS Command Processor + + +COUNTRY=nnn + + +Sets country-specific conventions in config.sys. Date and time formats are set in the country file. + + +CTTY Change terminal device +HC Command Processor + +Use the Psion SIBO Debugger, which provides similar functionality. + +Workabout Command Processor + +Use the Psion SIBO Debugger, which provides similar functionality. + +MS-DOS Command Processor + + +CTTY device + + +Change terminal device. + + +D Brief directory listing +HC Command Processor +D [/p] [filespec] + + +Lists specified filenames in a directory, without any additional information except for the total size and +the total number of bytes free on the current device. + + +Workabout Command Processor +The pir command has a switch (/») for bare output of filenames only. +MS-DOS Command Processor + + +The ptr command has many switches to format directory listing output. + + +DATA Run the database application + + +External command. + +HC Command Processor + +Not available. + +Workabout Command Processor + +[START] DATA [system::] [drive:] [path] [filename[.extension] ] +Run the database application, Data. + +MS-DOS Command Processor + + +Not available, though there are many proprietary programs on the market. + + +WORKABOUT PROGRAMMING GUIDE + + +DATE Display date [and time] + + +HC Command Processor + + +DAT IE] + +Displays the current date and time, in the format: +day/d[d]/mth/yyyy hh:mm:ss + +For example: +Thu/12/O0ct/1995 16:59:59 + + +will be displayed if the current system date and time is Thursday 12 October 1995, and it is one second +before five o'clock in the afternoon. + + +If the day of the month has only a single digit, no leading zero is displayed. One minute past noon on the +first day of January 1996 is displayed as: + + +Mon/1/Jan/1996 12:01:00 +The date must be set with serpat. + + +Workabout Command Processor + + +DATE + + +Displays the current date in the default format, or the format specified by the most recent sETDEF or menu +command. + + +The default display format is: +dd/mm/yy +For example 12/10/95 will be displayed if the current system date is 12 October 1995. + + +If the day of the month or the month number itself has only a single digit, a leading zero is displayed. The +first day of January 1996 is displayed as: + + +01/01/96 +The date must be set from the menus. See Time for displaying the system time. + + +MS-DOS Command Processor + + +DATE [mm-dd-yy] + + +Displays the current date, and prompts for it to be changed. Otherwise sets the date. + + +DBLSPACE Compress a disk + + +HC Command Processor + +Not supported. This is not relevant to Psion computers. +Workabout Command Processor + +Not supported. This is not relevant to Psion computers. +MS-DOS Command Processor + + +DBLSPACE + + +Compresses data on hard or floppy disks. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +DEBUG + + +HC Command Processor + +The Psion SIBO debugger offers similar functionality. +Workabout Command Processor + +The Psion SIBO debugger offers similar functionality. +MS-DOS Command Processor + + +DEBUG + + +Starts the debug program to allow debugging of executable files. + + +DEFRAG + + +HC Command Processor + + +Start the debug program + + +Optimise files on a disk + + +Use the compress command in Psion RCom or a "Compress..." option in PsiWin. + + +Workabout Command Processor + + +Use the compress command in Psion RCom or a "Compress..." option in PsiWin. + + +MS-DOS Command Processor + + +DEFRAG + + +Reorganises files on a disk to optimise disk performance. + + +DEL{ETE} + + +Deletes the specified file or files. + +HC Command Processor +DEL[ETE] filespec + +Workabout Command Processor +DEL filespec [/s] [/y] + +or + +ERASE filespec [/s] [/y] + + +If the /s flag is used, all subdirectories and files are deleted. + + +Delete file(s) + + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. +Note that, like in MS-DOS, confirmation is not asked for if a single file is being deleted. Unless /y is +used, confirmation is always asked for if all files in a directory are being deleted. + + +MS-DOS Command Processor +DEL filespec [/p] +or + + +ERASE filespec [/p] + + +If the /p flag is used, prompts for confirmation before deleting a specific file. + + +The DELTREE command is used to delete subdirectories and their files. + + +WORKABOUT PROGRAMMING GUIDE + + +DELTREE Delete a directory, subdirectories and files +HC Command Processor +Not available. +Workabout Command Processor +Use: +DEL filespec /s +or +ERASE filespec /s +MS-DOS Command Processor +DELTREE + + +Deletes a specified directory and all subdirectories and files. + + +DEVICE List devices + + +The Psion HC command performs a completely different function to the MS-DOS command. +HC Command Processor + +DEV[ICE] [filespec] + +Lists all devices ("drives") in the filing system specified by filespec. + +Workabout Command Processor + +Re[placed by LupEv and LppEv. + +MS-DOS Command Processor + +Loads a device driver. This is a config.sys command. + +DEVICE filespec + + +However the mem command provides similar functionality. + + +DIR Full directory listing + + +Lists all the specified files in a directory, together with their sizes, the time and date of their last +modification, and their attributes. + + +HC Command Processor + +DIR [/p] [filespec] + +The /p flag causes the display to pause at the end of each screen. +Workabout Command Processor + +DIR [drive:] [path] [filespec] [/s] [/b] + + +The listing pauses automatically after each screen of information, prompting the user to press enter to +continue, (except in batch files). + + +The /s flag causes all subdirectories to be listed as well. +The /b flag causes bare output to be used, (filenames only). +MS-DOS Command Processor + + +DIR [drive:] [path] [filespec] + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +DISKCOMP Compare two floppy disks + + +HC Command Processor + + +Not available. + + +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor + + +DISKCOMP + + +Compares two floppy disks. + + +DISKCOPY Copy a floppy disk + + +HC Command Processor +Not available. +Workabout Command Processor + + +Use copy *.* /s (note that this does not format the target disk). +Also available via a System Screen menu option for SSDs. + + +MS-DOS Command Processor +DISKCOPY + + +Copies a floppy disk. The target disk is formatted first. + + +DOSKEY Load/start DOSKEY program + + +HC Command Processor + +Not available. + +Workabout Command Processor +This functionality is built-in. +MS-DOS Command Processor +DOSKEY [] + + +Load/start the DOSKEY program. + + +DOSSHELL Load DOSSHELL graphical interface + + +HC Command Processor +Not available. +Workabout Command Processor + + +Not available. The System Screen carries out similar functions to the MS-DOS Shell. +This may be loaded directly from the Startup Shell, or by entering: + + +start sysS$gsys +in the Command Processor. + + +MS-DOS Command Processor + + +DOSSHELL + + +Loads the MS-DOS Shell graphical interface. + + +WORKABOUT PROGRAMMING GUIDE + + +ECHO Display message, set or display echo mode +Displays the message text, or sets the echo mode in batch files, or displays the current echo mode. + +HC Command Processor + +Not supported. + +Workabout Command Processor + +ECHO [[text]|[ON | OFF]] + + +MS-DOS Command Processor + + +ECHO [[text]|[ON | OFF]] + + +EDIT Run file editor + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +[START] EDIT [system::] [drive:] [path] [filename] [.extension] + + +Runs the Psion file editor, which also translates and runs programs as determined by the source file +extension. + + +MS-DOS Command Processor +EDIT + + +Runs the MS-DOS text file editor. This is an external command. + + +EMM386 Enable expanded memory +HC Command Processor + +This is not relevant to Psion computers. + +Workabout Command Processor + +This is not relevant to Psion computers. + +MS-DOS Command Processor + +EMM386 + + +Enable EMM386 expanded memory. + + +ENV Display, set or delete environment variable +HC Command Processor + +ENV [[var[=[value]]]|[varspec]] + +Displays or sets the value of environment variables, or deletes them. + +Workabout Command Processor + +Not supported. + +The set command, which is exactly equivalent, must be used instead. + +MS-DOS Command Processor + + +Not available. The set command is used instead. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +ERASE Delete file(s) +HC Command Processor + +Not supported. + +DEL[ETE] must be used instead. + + +Workabout Command Processor + + +ERASE [drive:] [path] filespec [/s] [/y] +Deletes the specified file or files. +The command DEL filespec [/s] [/y] is exactly the same as ERASE. + + +MS-DOS Command Processor + + +ERASE [drive:] [path] filespec [/p] + + +Deletes the specified file or files. + + +The command DEL filespec [/p] is exactly the same as ERASE. + + +ERRLEVEL Display error level + + +Display the error level. + +HC Command Processor + +Not supported. + +Workabout Command Processor +ERRLEVEL + +Display the error level state (TRUE or FALSE). +MS-DOS Command Processor + +Not supported. + + +ERRORLEVEL Error level value + + +ERRORLEVEL 18 not a command. It is the status of the last command that was executed. +HC Command Processor + +Not supported. + +Workabout Command Processor + + +ERRORLEVEL + + +Holds the error level value, (it is a Boolean value, TRuE or FALSE). Unlike DOS, Command Processor +commands set ERRORLEVEL as applicable. The general use of ERRORLEVEL is in an IF statement: + + +IF [NOT] ERRORLEVEL command + + +Thus, for example, within a batch file, you can test for a directory, as follows: + + +CHDIR \INC +IF ERRORLEVEL MD \INC +CHDIR \INC + + +MS-DOS Command Processor + + +ERRORLEVEL +Holds the error level number (an integer in the range 0 to 255). An example of its use is: + + +IF [NOT] ERRORLEVEL number command + + +WORKABOUT PROGRAMMING GUIDE + + +EXIT Exit level + + +HC Command Processor + + +EXI[T] + + +Exits the Command Shell. May be used to terminate second copies of the Command Shell that are no +longer required. + + +If the exrT command is typed into the first copy of the Command Shell, the HC will automatically +re-launch a shell process, as explained in the Introduction to the HC chapter of the HC User Reference +manual. + + +If the rxrT command is found in a batch file, all that happens is that the batch file is terminated, and +control passes back to the previous level of batch file (or to the command line). See the Workabout +Command Processor gurt command. + + +Workabout Command Processor +EXIT +Present a dialog offering options to terminate the Command Processor or cancel the command. + + +On confirmation of an ExT command typed directly into the Command Processor (or of the selection of +the Exit option from the Special menu) the Command Processor is terminated. If there is no other task +running on the machine, the Workabout will then automatically bring the Startup Shell process to +foreground, as explained in the chapter Introduction to the Workabout. If one or more other tasks are +running, the machine will switch tasks to whichever running application was last used. + + +If the rxrT command is executed from a (nested) batch file, all levels of batch processing are terminated +immediately and the confirmation dialog presented. On confirming the rx1tT command, the Command +Processor terminates in the same way as when ex1T is typed directly into the Command Processor. + + +MS-DOS Command Processor + + +EXIT +Terminates the Command Processor. + + +If the extT command is found in a batch file, all levels of batch processing are terminated. The Command +Processor terminates in the same way as when ex1T Is typed directly into the Command Processor. + + +EXPAND Expand a compressed file + + +HC Command Processor + + +Not available. + + +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor + + +EXPAND + + +Expand a compressed file. + + +FASTHELP Get summary Help on command syntax +HC Command Processor + +Not available. + +Workabout Command Processor + + +Not available. Use HELP [command] + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MS-DOS Command Processor +FASTHELP [command] + +or + +[command] /? + + +Gets summary Help as a listing of (all) command(s) and syntax. +MS-DOS 6 onwards, (it is the same as HELP in MS-DOS 5) + + +FASTOPEN Start FASTOPEN program + + +HC Command Processor + +Not available. This is not relevant to Psion computers. +Workabout Command Processor + +Not available. This is not relevant to Psion computers. + + +MS-DOS Command Processor + + +FASTOPEN + + +Starts the FASTOPEN program. + + +FC Compare two files +HC Command Processor + +Not available. + +Workabout Command Processor + +Not available. + + +MS-DOS Command Processor + + +FC + + +Compares two files and lists the differences between them. External command, MS-DOS 6 onwards, (c.f. +comp in MS-DOS 5). + + +FCBS Specify number of file control blocks +HC Command Processor + +Not available. This is not relevant to SIBO machines. + +Workabout Command Processor + +Not available. This is not relevant to SIBO machines. + + +MS-DOS Command Processor + + +FCBS + + +Specifies the number of file control blocks (FCBs) that can be open at any one time. Used in config.sys +files only. + + +FDISK Partition a hard disk +HC Command Processor + +Not available. This is not relevant to SIBO machines. + +Workabout Command Processor + +Not available. This is not relevant to SIBO machines. + + +MS-DOS Command Processor + + +FDISK + + +Starts the MS-DOS FDISK program to partition a hard disk. This is an external command. + + +WORKABOUT PROGRAMMING GUIDE + + +FILES List open files/Specify number of files accessible +This command is completely different for MS-DOS and SIBO machines. + + +HC Command Processor + + +Not available. + + +Workabout Command Processor + + +FILES drive: +Returns the names of all open files on the specified drive. +The program using each file, the process number and the full filename including the path are given. + + +MS-DOS Command Processor + + +FILES=x +Specifies the number of files MS-DOS can access at one time. Used in config.sys files only. + + +Some networks provide a functionality similar to the Workabout r1Lzes command. + + +FIND Find a text string in a file or files +HC Command Processor + +Not available. + +Workabout Command Processor + +Not supported. + + +MS-DOS Command Processor + + +FIND + + +Searches for a specified text string in a file or files. + + +FOR Run a command for the files in a set +Run a command for each file in a specified set of files. + +HC Command Processor + +Not supported. + + +Workabout Command Processor + + +FOR %[%]variable IN (set) DO command [parameters] +The extra % is needed in batch programs. + + +MS-DOS Command Processor + + +FOR %[%]variable IN (set) DO command [parameters] + + +The extra s is needed in batch programs. + + +FORMAT Format device + + +Formats a disk in the specified drive. +The disk may be labelled with a volume name (label), volname + + +HC Command Processor +FOR[MAT] [drive:] [volname] +Workabout Command Processor +FORMAT [drive:] [volname] + + +If the label voiname is not specified, any existing label is retained. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MS-DOS Command Processor +FORMAT + + +If the label is not specified, any existing label is deleted. + + +FREE Display free memory +HC Command Processor + +FRE [E] + +Displays the amount of free RAM in kilobytes. + +Workabout Command Processor + +The mem command performs a similar function. + +MS-DOS Command Processor + + +The mem command performs a similar function. + + +GOTO Jump to label in batch file + + +Jump to the label 1abe1 in a batch file. A label in a batch file occurs at the start of a line (preceded by a +colon, :). It is not the same thing as the label mentioned in the rormat and LaBEL command descriptions. + + +HC Command Processor + +Not supported. + +Workabout Command Processor +GOTO label + +MS-DOS Command Processor + + +GOTO label + + +GRAPHICS Load program to allow printing of colour screen +HC Command Processor + +Not available. The HC has black and white graphics by default. + +Workabout Command Processor + +Not available. The Workabout has black, grey and white graphics by default. + +MS-DOS Command Processor + +GRAPHICS + + +Loads a program to allow the printing of information displayed on a colour screen. Used in config. sys files +only. + + +HELP List commands or get help + + +List commands or get help on a specific command. +HC Command Processor + +Not supported. + +Workabout Command Processor + +HELP [command] + +MS-DOS Command Processor + + +HELP [command] + + +WORKABOUT PROGRAMMING GUIDE + + +IF Run command conditionally + + +A command is run depending on one of three possible specified conditions. See also ERRORLEVEL. + +HC Command Processor + +Not supported. + +Workabout Command Processor + +IF [not] {ERRORLEVEL | stringl==string2 | EXIST filespec} command [command_parameters] + + +The file specification can consist of a system and double colon, drive letter and colon, a directory name, a +filename, or a combination of these. + + +MS-DOS Command Processor + + +IF [not] {ERRORLEVEL nn | stringl==string2 | EXIST [[drive:]path]filename} command + + +INSTALL Install memory resident program + + +HC Command Processor + + +Not supported. SIBO computers are multi-tasking, so can have many programs running at the same time. +Use sprogname in a batch file for a similar effect to MS-DOS rnstatt. + + +Workabout Command Processor + + +Not supported. SIBO computers are multi-tasking, so can have many programs running at the same time. +Use the start command in a batch file for a similar same effect to MS-DOS tnstatt. + + +MS-DOS Command Processor + + +INSTALL [drive:][path]filename [command-parameters] + + +Installs a memory resident program when MS-DOS is started up. Can only be used in config.sys files. + + +INTERLNK Connect two computers to share resources + + +HC Command Processor +Use tink and MCLINK or RCom, or PsiWin. + + +Workabout Command Processor +Use tink and MCLINK or RCom, or PsiWin. + + +MS-DOS Command Processor + + +INTERLNK [client[:]=[server][:]] + + +Connects two computers using Interlink. MS-DOS 6.0 onwards. + + +INTERSVR Start the Interlink server + + +HC Command Processor + +Use tink and MCLINK or RCom, or PsiWin. +Workabout Command Processor + +Use tinx and MCLINK or RCom, or PsiWin. +MS-DOS Command Processor +INTERSVR + + +Starts the Interlink server. MS-DOS 6.0 onwards. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +KEYB Configure keyboard for language +HC Command Processor + +Not supported. + +Workabout Command Processor + +Use setpEF to set the keyboard, (or the system interface menu option). + + +MS-DOS Command Processor + + +KEYB + + +Configures the keyboard for a particular language. + + +KILL Kill a process +Kills the first process found matching the specification in procname. Emergency use only. See stop. + +HC Command Processor + +KIL[L] procname + +Workabout Command Processor + +KILL procname [/y] + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + +MS-DOS Command Processor + +Not supported. + + +LABEL Add/alter disk volume label + + +Creates, changes or deletes the label on an SSD/disk in the specified drive, (using the label name). +HC Command Processor + +Not supported. + +Workabout Command Processor + +LABEL [drive:] [name] + + +MS-DOS Command Processor + + +LABEL [drive:] [name] +LASTDRIVE Specify maximum number of drives +LDEV List device drivers + + +Lists all specified logical and physical device drivers. + +HC Command Processor + +LDEV [device_spec] + +Workabout Command Processor + +There are separate commands to list logical and physical device drivers, LLpDEV and LPDEV. +MS-DOS Command Processor + + +Not supported. The mem command provides a similar function. + + +WORKABOUT PROGRAMMING GUIDE + + +LH Load program into upper memory +HC Command Processor + +Not relevant to SIBO machines. + +Workabout Command Processor + +Not relevant to SIBO machines. + + +MS-DOS Command Processor + + +LH + + +Load a program into the upper memory area, or into a specified region or regions of upper memory. This +is the same as LOADHIGH. + + +LLDEV List logical device drivers +Lists all specified logical device drivers. + +HC Command Processor + +The tpEv command lists both physical and logical device drivers. + +Workabout Command Processor + +LLDEV [device_spec] + +The list includes all ROM-resident device drivers, as well as external ones that are currently loaded. +MS-DOS Command Processor + + +Not supported. The mem command provides a similar function. + + +LOADFIX Load and run program above first 64K block +HC Command Processor + +Not relevant to SIBO machines. + +Workabout Command Processor + +Not relevant to SIBO machines. + + +MS-DOS Command Processor + + +LOADFIX + + +Loads a program into memory above the first 64KB block of conventional memory, and runs it. + + +LOADHIGH Load program into upper memory +HC Command Processor + +Not relevant to SIBO machines. + +Workabout Command Processor + +Not relevant to SIBO machines. + + +MS-DOS Command Processor + + +LOADHIGH + + +Loads a program into the upper memory area, or into a specified region or regions of upper memory. This +is the same as LH. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +LOWBAT Configure low battery warnings + + +HC Command Processor +LOW[BAT] state + + +If state is on, the HC will check, each time the HC is switched on, for either of the batteries being low. +On detecting a low battery, the HC will issue a warning. This will be in the form of an information +message in the bottom right-hand corner of the screen. + + +If state is orF, this behaviour will not take place. This is the default. +Workabout Command Processor + + +Not supported. On detecting a low battery when switched on, the Workabout will issue a warning. This +will be in the form of an information message in the bottom right-hand corner of the screen. There is no +command to switch this behaviour off. Use Shift-Ctrl-B for battery information at any time. + + +MS-DOS Command Processor +Not supported. + + +LPDEV List physical device drivers + + +Lists all specified physical device drivers. + +HC Command Processor + +Not supported. The Lpzv command lists both physical and logical device drivers. + +Workabout Command Processor + +LPDEV [device_spec] + +The list includes all ROM-resident device drivers, as well as external ones that are currently loaded. +MS-DOS Command Processor + + +Not supported. The mem command provides a similar function. + + +LPROC List processes + + +Lists information about all specified processes. +HC Command Processor + +LPR[OC] [process_spec] + +Workabout Command Processor + +LPROC [process_spec] + + +This command is identical to that on the HC, except that the information is displayed slightly differently, +(e.g. the number of matching processes is given). + + +MS-DOS Command Processor + + +Not supported. The mem command provides a similar function. + + +LSEG List segments + + +Lists all memory segments currently in use by the specified process(es). +HC Command Processor + +LSE[G] [process_spec] + +Workabout Command Processor + + +LSEG [process_spec] + + +This command is identical to that on the HC, except that the information is displayed slightly differently, +(e.g. the number of matches found is given). + + +MS-DOS Command Processor +Not supported. + + +WORKABOUT PROGRAMMING GUIDE + + +MASTER Display time and date of mastering + + +HC Command Processor +MAS [TER] + + +Displays the time and date when the ROM was mastered. + + +Workabout Command Processor + + +Not supported. This command is not relevant since the ROM cannot be reprogrammed. the time and date +of mastering is given, however, by the ver command. + + +MS-DOS Command Processor +Not supported. + + +MD Make directory + + +Make a directory. This command is almost identical on all three types of machine. + + +HC Command Processor +MD [system::] [drive:]path + + +A trailing backslash can be used in the path component. + + +Workabout Command Processor +MD [system::] [drive:]path + + +A trailing backslash can be used in the path component. + + +MS-DOS Command Processor +MD [drive:]path + + +A trailing backslash cannot be used in the path component. + + +MEM Display free memory +HC Command Processor + +The identical rREz command must be used instead. + +Workabout Command Processor + + +MEM + + +Displays the amount of free RAM in kilobytes that is available to programs. More detailed information on +memory usage is available from the "Memory info" option of the "Info" menu in the System Screen. + + +MS-DOS Command Processor + + +MEM + + +Displays the amount of free and used RAM in kilobytes, or more specific aspects of memory usage. + + +MEMMAKER Optimise computer's memory +HC Command Processor + +Not supported. Not relevant to SIBO machines. + +Workabout Command Processor + +Not supported. Not relevant to SIBO machines. + +MS-DOS Command Processor + +MEMMAKER + + +Optimises the computer's memory usage. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MENUCOLOR Set startup menu colours + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +The Workabout has a built-in menu system.. +MS-DOS Command Processor +MENUCOLOR + + +Sets the foreground and background colours for the startup menu. Can only be used in config.sys files. +MS-DOS 6.0 onwards. + + +MENUDEFAULT Set startup menu item and timeout + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +The Workabout has a built-in menu system. +MS-DOS Command Processor +MENUDEFAULT + + +Sets the default highlighted item on the startup menu, and the timeout. Can only be used in config.sys +files. MS-DOS 6.0 onwards. + + +MENUITEM Define startup menu item + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +The Workabout has a built-in menu system. +MS-DOS Command Processor +MENUITEM + + +Defines an item on the startup menu. Can only be used in config.sys files. MS-DOS 6.0 onwards. + + +MKDIR Make directory + + +Makes a directory. + +HC Command Processor + +Not supported. The identical my command must be used instead. +Workabout Command Processor + +MKDIR [drive:]path + +A trailing backslash can be used in the path component. +MS-DOS Command Processor + +MKDIR [drive:]path + + +A trailing backslash cannot be used in the path component. + + +WORKABOUT PROGRAMMING GUIDE + + +MODE Configure system devices +HC Command Processor + +The n1nk command and Communications Scripts can perform similar functions. + +Workabout Command Processor + +The t1nk command and Communications Scripts can perform similar functions. + +MS-DOS Command Processor + +MODE + + +Configure system devices. + + +MORE Display output one screenful at a time +HC Command Processor + +The Psion-Left key combination is used to pause output in the Command Processor. + +Workabout Command Processor + + +The Workabout Command Processor pauses automatically after each screenful of output, except during +batch file execution. + + +MS-DOS Command Processor +MORE + + +Displays output one screenful at a time. + + +MOVE Move file(s) + + +HC Command Processor + +A combination of copy and pe must be used. +Workabout Command Processor + +A combination of copy and pEL must be used. +MS-DOS Command Processor + +MOVE + + +Moves a file or files to a specified location. + + +MSAV Scan for viruses + + +HC Command Processor + +Not supported. + +Workabout Command Processor +Not supported. + +MS-DOS Command Processor +MSAV + + +Scans for viruses. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MSBACKUP Run backup program + + +HC Command Processor + +The MCLINK, RCom and PsiWin programs all include backup and restore facilities. +Workabout Command Processor + +The MCLINK, RCom and PsiWin programs all include backup and restore facilities. +MS-DOS Command Processor + +MSBACKUP + + +Runs the Microsoft Backup for MS-DOS program to backup or restore files, (MS-DOS 6.0). + + +MSCDEX Provide CD-ROM access + + +HC Command Processor +The MCLINK, RCom and PsiWin programs all include remote file access facilities. + + +Workabout Command Processor +The MCLINK, RCom and PsiWin programs all include remote file access facilities. + + +MS-DOS Command Processor +MSCDEX +Provides access to CD-ROM drives. + + +MSD Provide technical details + + +HC Command Processor + +Not supported. + +Workabout Command Processor +Not supported. + +MS-DOS Command Processor +MSD + + +Provides technical details about your computer. + + +NLSFUNC Load country-specific information + + +HC Command Processor + + +The language data file may be changed by using the conric command. + + +Workabout Command Processor + + +The characters available from the keyboard may be changed by defining the keyboard to use via the +SETDEF command. + + +MS-DOS Command Processor +NLSFUNC + + +Loads country-specific information for national language support (NLS). + + +NOTIFY Control whether the Notifier appears + + +HC Command Processor + + +NOT[IFY] state + + +Controls whether the Notifier ever appears as a result of a file operation carried out by the Command +Shell. + + +Workabout Command Processor +A notifier always appears when required. + + +MS-DOS Command Processor +Not supported. + + +WORKABOUT PROGRAMMING GUIDE + + +NUMLOCK Start with Num Lock on/off + + +HC Command Processor + +Not supported. + +Workabout Command Processor +Not supported. + + +MS-DOS Command Processor + + +NUMLOCK [ON|OFF] + + +Specifies whether the Num Lock key is ON or OFF when the computer starts. Can only be used in +config. sys files. + + +OFFENABLE Enable off-key handling + + +HC Command Processor + + +OFFE[NABLE] value + + +If value is 0, the Command Shell gives up its capture of the OFF key, thereby allowing other applications +to capture this key to do their own processing of it. + + +If value is any non-zero number, the Command Shell attempts to capture the OFF key again. +Workabout Command Processor +The Window Server always captures the Off key. + + +MS-DOS Command Processor +Not supported. + + +PATH Specify search path for executable files +HC Command Processor + +SIBO computers have built in search routines for executable files. + +Workabout Command Processor + +SIBO computers have built in search routines for executable files. + +MS-DOS Command Processor + +PATH + + +Specifies or displays the search path for executable files. + + +PAUSE Suspend batch file processing + + +Suspend batch file processing. + +HC Command Processor + +Not supported. + +Workabout Command Processor + +PAUSE [text] + +Any associated message may be given in the text. +MS-DOS Command Processor + +PAUSE + + +A "Press any key to continue" message is displayed, but a separate EcHo statement is needed to display any +other associated message. MS-DOS 5.0 onwards. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +POWER Power saving set/display/on/off + + +HC Command Processor + +Power saving features are an integral part of SIBO machines. See the auto command, etc. +Workabout Command Processor + +Power saving features are an integral part of SIBO machines. See the setpEF command,. +MS-DOS Command Processor + +POWER + + +Turns power-saving on and off, displays power saving status and sets power saving parameters. + + +PRINT Print text file in background + + +HC Command Processor + +Other processes (tasks) may print while the Command Processor is being used. +Workabout Command Processor + +Other processes (tasks) may print while the Command Processor is being used. +MS-DOS Command Processor + +PRINT + + +Prints a text file as a background activity. + + +PROMPT Change command prompt + + +HC Command Processor + +Not supported. Restricted screen size limits the practical size for the prompt. +Workabout Command Processor + +Not supported. Restricted screen size limits the practical size for the prompt. +MS-DOS Command Processor + +PROMPT [text] + + +Changes the appearance of the command prompt. + + +QBASIC Run QBasic language + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +Not supported. An OPL program editor and translator is provided in the ROM as standard, (see EDIT). +MS-DOS Command Processor + +QBASIC + + +Runs the MS-DOS QBasic language interpreter. + + +QUIT Exit current batch file only + + +HC Command Processor + +Not supported. + +Workabout Command Processor + +QUIT + +Exits the current batch file only. + +MS-DOS Command Processor + +Not supported. Use Goto 1abe1 where :1abe1 1s the last line of the batch file. + + +WORKABOUT PROGRAMMING GUIDE + + +RD Remove directory + + +HC Command Processor + + +RD [drive:]path + +Workabout Command Processor + +RD [drive:]path [/y] + +Deletes a directory, including any files in it (and subdirectories). + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. +MS-DOS Command Processor + +RD [drive:]path + + +Deletes an empty directory only. + + +REASON Get the cause of the last system shutdown +HC Command Processor +Not supported. A message is, however, displayed automatically on switch-on after a system shutdown. + + +Workabout Command Processor + + +REASON +Returns a code indicating the cause of the last system shutdown. + + +MS-DOS Command Processor +Not supported + + +REM Comment (remark) in batch file +Comment (remark) in a batch file. + +HC Command Processor + +Not supported. + +Workabout Command Processor + +REM [text] + +A semicolon (; ) cannot be used instead of rem. + + +MS-DOS Command Processor + + +REM [text] + + +A semicolon (; ) can be used instead of rem in config.sys files, but not batch files. + + +REN{AME} Rename file(s) + + +Changes the name of a file or files. + +HC Command Processor + +REN[AME] [drive:] [path]filenamel filename2 +Workabout Command Processor + +REN [drive:] [path]filenamel filename2 +MS-DOS Command Processor + + +RENAME [drive:] [path]filenamel filename2 + + +or + + +REN [drive:][path]filenamel filename2 + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +REPLACE Replace file(s) +HC Command Processor + +Not supported. + +Workabout Command Processor + +Not supported. + + +MS-DOS Command Processor + + +REPLACE + + +Replaces the files in one directory with those of the same name from another directory. + + +RESTORE Restore file(s) + + +HC Command Processor +Not supported. Files are restored from a PC using MCLINK, RCom or PsiWin. + + +Workabout Command Processor +Not supported. Files are restored from a PC using MCLINK, RCom or PsiWin. + + +MS-DOS Command Processor + + +RESTORE + + +Restores backed up files from one disk to another, (MS-DOS 2.0 to 5.0). + + +RESUME Resume a suspended process + + +HC Command Processor + +RES [UME] procname + +Resumes the previously suspended process procname. +Workabout Command Processor + +Not supported. + +MS-DOS Command Processor + +Not supported. + + +RMDIR Remove directory + + +HC Command Processor + +Not supported. The rp command must be used instead. + +Workabout Command Processor + +RMDIR [drive:]path [/y] + +Deletes a directory, including any files in it (and subdirectories). + +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. +MS-DOS Command Processor + +RMDIR [drive:]path + + +Deletes an empty directory only. + + +SCANDISK Analyse/repair disk(s) + + +HC Command Processor +Not supported. Not relevant to SSDs. + + +Workabout Command Processor +Not supported. Not relevant to SSDs. + + +B - 31 + + +WORKABOUT PROGRAMMING GUIDE + + +MS-DOS Command Processor +SCANDISK + + +Runs the Microsoft ScanDisk program to analyse a disk or disks and repair any errors. + + +SET Set default path/environment variables + + +This command does completely different things on each machine. + + +HC Command Processor +SET path +Sets the system-wide default path. + + +Workabout Command Processor + +SET [[var[=[value]]]|[varspec]] + +Displays or sets the value of, or deletes, environment variables. +Equivalent to env on the HC. + + +There is no single command to set the default path on the Workabout. The drive letter followed by a colon +should be used to set the current drive in the Command Processor or batch files , and the CD command to +change the current directory. + + +MS-DOS Command Processor +SET [var=[string] ] + + +Displays or sets the value of, or deletes, environment variables. + + +SETDATE Set date and time + + +HC Command Processor +SETD[ATE] dd/mm/yy hh:mm:ss + +Sets the date and time. + +Workabout Command Processor + + +Not supported. Date and time must be set from the menu of the Command Processor or System Screen. + + +MS-DOS Command Processor + + +Not supported. Date and time must be set using the patz and trmz commands. + + +SETDEF Alter system settings + + +HC Command Processor +Not supported. + + +The machine configuration is set using the AUTO, BACKLIGHT, BATTERY, CONFIG, LOWBAT, NOTIFY, +OFFENABLE and wnotiry commands. The configurability is completely different for the HC. + + +Workabout Command Processor + + +SETDEF [AMnn] [ABnn] [DDMY | DMDy | DYMD] [Dn] [KO | K1] [s+ | S-] [112 | 124] [TS+ | TS-] +Alter system settings, (which are otherwise set by menu options). + + +MS-DOS Command Processor + + +Not supported. Date and time formats are set in the country file, using the country command. + + +B - 32 + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +SETVER Report MS-DOS version or display/update version table +HC Command Processor + +Not supported. Not relevant to SIBO machines. + +Workabout Command Processor + +Not supported. Not relevant to SIBO machines. + +MS-DOS Command Processor + +SETVER + + +Displays the MS-DOS version table. Reports a version number (earlier than the installed version) to +programs or device drivers. Allows the version table to be updated. + + +SHARE Install file sharing and locking +HC Command Processor + +Built into the EPOC Operating System of all SIBO machines. + +Workabout Command Processor + +Built into the EPOC Operating System of all SIBO machines. + +MS-DOS Command Processor + +SHARE + + +Installs file sharing and locking capabilities on local and/or network drives. + + +SHELL Specify command interpreter + + +HC Command Processor + + +Alternative command processors can be installed on HC machines - see the Customising an HC section of +the Introduction to the HC chapter of the HC Programmers Reference manual. + + +Workabout Command Processor + + +Alternative command processors can be installed on Workabout machines - see the Customising a +Workabout section of the Introduction to the Workabout chapter of the Workabout Programmers +Reference manual. + + +MS-DOS Command Processor +SHELL + + +Specifies the name and location of the command interpreter to use. Can only be used in config. sys files. + + +SHIFT Shift batch file parameters + + +Moves the replaceable parameters of a batch file one position to the left. Thus 1 becomes s0, s9 becomes +$8, etc. + + +HC Command Processor + +Not supported. + +Workabout Command Processor +SHIFT + +MS-DOS Command Processor +SHIFT + + +WORKABOUT PROGRAMMING GUIDE + + +SMARTDRV Setup/configure disk cache/buffering +HC Command Processor + +Not supported. Not relevant to SIBO machines using SSDs and RAMdrives. + +Workabout Command Processor + +Not supported. Not relevant to SIBO machines using SSDs and RAMdrives. + + +MS-DOS Command Processor + + +SMARTDRV + + +Sets up or configures MS-DOS SMARTDrive which creates a disk cache in extended memory, or +performs double buffering. + + +SORT Read, sort and write data +HC Command Processor + +Not supported. + +Workabout Command Processor + +Not supported. + + +MS-DOS Command Processor + + +SORT + + +Reads input, sorts data and writes output to screen a file or another device. + + +START Start a process asynchronously + + +HC Command Processor + + +Not supported. Processes are started asynchronously by simply entering their name, +(unless preceded by &). + + +Workabout Command Processor + + +START procname +Launch the given process and return immediately. +Starts the first process found matching the specification in procname, (asynchronously). + + +MS-DOS Command Processor +Not supported. MS-DOS is not multitasking. + + +STOP Stop a process + + +HC Command Processor + + +Not supported. This is identical to TER {mINATE] on the HC, except that TER[MINATE] only stops the first +process matching the specification. + + +Workabout Command Processor + + +STOP procname [/y] +Terminates the named process or processes matching the specification in procname. +If the /y flag is used, no confirmation is asked for. This is intended for use in batch files. + + +MS-DOS Command Processor +Not supported. + + +B - 34 + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +SUBMENU Specify startup menu item as a submenu + + +HC Command Processor +Not supported. +Workabout Command Processor + + +Not supported. The Workabout has a built-in menu system. + + +MS-DOS Command Processor + + +SUBMENU + + +Specifies an item in the startup menu as giving a submenu when selected. Can only be used in config.sys +files. MS-DOS 6.0 onwards. + + +SUBST Associate path with drive letter + + +HC Command Processor + +Not supported. + +Workabout Command Processor +Not supported. + +MS-DOS Command Processor +SUBST + + +Associates a path with a drive letter. + + +SUSPEND Suspend a process + + +HC Command Processor + +SUS[PEND] procname + +Suspends the first process found matching the specification in procname. +Workabout Command Processor + +Not supported. + +MS-DOS Command Processor + +Not supported. + + +SYS Make a startup disk + + +HC Command Processor + +Not relevant to SIBO machines. +Workabout Command Processor +Not relevant to SIBO machines. +MS-DOS Command Processor +SYS + + +Creates a boot disk containing hidden system files, the command processor, etc. + + +TERMINATE Terminate a process + + +HC Command Processor + +TER[MINATE] procname + +Terminates the first process found matching the specification in procname. +Workabout Command Processor + +Not supported. Replaced by: + + +STOP procname + + +B - 35 + + +WORKABOUT PROGRAMMING GUIDE + + +This is identical to TER[mMINATE] on the HC, except that all processes matching the specification procname +are terminated. + + +MS-DOS Command Processor +Not supported. MS-DOS is not multitasking. + + +TIME Display/(set) time +HC Command Processor +Not supported. pate displays both the current system date and time. + + +Workabout Command Processor + + +TIME + + +Displays the current time, in the default format, or that specified by the most recent seTDEF or menu +command. Time must be set via the menu system. + + +MS-DOS Command Processor + + +TIME [hours: [minutes[:seconds[.hundredths]]][A|P]] + + +Displays the system time or sets your computer's internal clock. + + +TREE Display directory graphically +HC Command Processor + +Not supported. + +Workabout Command Processor + +Not supported. + + +MS-DOS Command Processor + + +TREE + + +Displays a directory graphically. + + +TYPE Type a text file + + +Prints a text or batch file to the screen. +HC Command Processor +TY[PE] filename + + +There is no provision for the display to pause itself automatically. However, the user can pause the display +at any time, in the usual way, by pressing PSION-LEFT. + + +Workabout Command Processor + + +TYPE filename +The display pauses itself automatically after each screen full of text. + + +MS-DOS Command Processor + + +TYPE filename + + +UNDELETE Restore deleted files + + +HC Command Processor +Not available. +Workabout Command Processor + + +Not available. + + +APPENDIX B - COMMAND PROCESSOR DIFFERENCES + + +MS-DOS Command Processor + + +UNDELETE + + +Restores files previously deleted using the pEL or ERASE command. + + +UNFORMAT Restore a formatted disk + + +HC Command Processor +Not available. +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor + + +UNFORMAT + + +Restores a disk previously erased by using the rormMat command. + + +VER Display software version numbers +HC Command Processor +VER[SION] + + +Displays the (EPOC) Operating System version number, the (HC) ROM version number, and the +(Command) Shell version number. + + +Workabout Command Processor + + +VER + + +Displays the (Workabout) ROM version number, the date and time that the ROM was mastered, the +(EPOC) Operating System version number, the Shell version number and the Command Processor version +number. + + +MS-DOS Command Processor + + +VER + + +Displays the MS-DOS version number. + + +VERIFY Turn disk write verification on/off + + +HC Command Processor +Not available. +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor + + +VERIFY [ON|OFF] + + +Switches disk write operation verification on or off. + + +VOL Display the disk volume label etc +HC Command Processor +Not supported. + + +Workabout Command Processor +VOL [system::] [drive:] + + +Displays the system, drive, volume label, media type, free space and total space for the disk volume in the +current or specified drive. + + +B - 37 + + +WORKABOUT PROGRAMMING GUIDE + + +MS-DOS Command Processor + + +VOL [drive:] + + +Displays the volume label and serial number of the disk volume in the current or specified drive. + + +VSAFE Continuously check for viruses + + +HC Command Processor + + +Not available. + + +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor + + +VSAFE + + +Continuously monitors the computer for viruses. + + +WAIT Wait for a process to complete + + +Wait until a process completes. + + +HC Command Processor + + +WAI [T] +The process cannot be named. + + +Workabout Command Processor + + +WAIT [procname] +A process name may be given if required. +Suspends the Command Processor until the applicable process completes. + + +MS-DOS Command Processor +Not supported. MS-DOS is not multitasking. + + +WNOTIFY Configure Notifier appearance + + +HC Command Processor + + +WNO[TIFY] state +Configures the appearance of the Notifier. + + +Workabout Command Processor + + +Not available. + + +MS-DOS Command Processor +Not supported. + + +XCOPY Copy directories, subdirectories and files + + +HC Command Processor + +Not available. + +Workabout Command Processor +Use copy /s. + + +MS-DOS Command Processor + + +XCOPY + + +Copies directories, their subdirectories and the files in those subdirectories. + + +APPENDIX C + + +DIFFERENCES BETWEEN + + +THE SERIES 3A/3C SYSTEM SCREEN AND THE + + +WORKABOUT SYSTEM SCREEN AND COMMAND + + +PROCESSOR MENUS + + +Introduction + + +About this appendix + + +This appendix compares the Psion Series 3a/3c System Screen with the options of the Workabout System +Screen and the Workabout Command Processor menus. Where relevant related Psion HC and Psion Siena +features are also included. It is provided to highlight the differences between the machines so that +developers may easily adapt to working with (and designing user interfaces for) the Workabout. + + +Principal differences centre on: + + +restricted screen size + + +different keyboard +backlight + +ports + +sound + + +built in applications + + +menu names need to be abbreviated + +less options can be fitted on each menu + +the analogue clock is too big for the Workabout and Siena Status/Info windows +icons are too big for the Workabout status window + +certain keys are not present (Diamond, Icon buttons) + +not present on the Series 3a or Siena, available on Series 3c variant + +the Workabout can have several ports + +the Series 3a/3c has digital sound recording and playback + + +the Time and World applications are not present on the Workabout, (Data, Calc, +Sheet, Program, RunOpl, Comms, Script and RunImg applications are present) + + +WORKABOUT PROGRAMMING GUIDE + + +Note that the Workabout Command Processor is only mentioned where relevant since it has only a small +number of menus, menu options and corresponding hotkeys. + + +Hotkeys + + +When assigning "hotkeys" ("accelerators") to certain key combinations in the applications that you write it +is important to note the differences that exist between the Psion HC, the Series 3a/3c, Siena and the +Workabout. + + +Psion-A Assign button/Set auto switch off times + + +Psion Series 3a/3c and Siena System Screen + + +mt + + +The Psion-A hotkey brings up the 'Assign button to "Icon_button +name above one of the Series 3a/3c icon buttons. + + +dialog, where "Icon_button" is the + + +Workabout System Screen + + +There is no "Assign button" option on the 'File’ menu. The Psion-A hotkey brings up the "Set auto switch +off times" dialog instead. + + +Psion-B/Shift-Ctrl-B Battery info +Psion Series 3a/3c and Siena System Screen +The Psion-B hotkey brings up the 'Battery info' dialog in the System Screen only. + + +Workabout System Screen +The Psion-B hotkey does nothing. For battery information Shift-Ctrl-B can be used at any time. + + +Shift-Psion-D Dialling +Psion Series 3a/3c and Siena System Screen + +The Shift-Psion-D hotkey brings up the 'Dial settings’ dialog, (not present on the Siena). + +Workabout System Screen + +The Shift-Psion-D hotkey does nothing. + + +Shift-Psion-E “Evaluate” format +Psion Series 3a/3c and Siena System Screen + +The Shift-Psion-E hotkey brings up the 'Set "Evaluate" format’ dialog. + +Workabout System Screen + +The Shift-Psion-E hotkey does nothing. + + +Psion-F Format disk/Time and date format +Psion Series 3a/3c and Siena System Screen + +The Psion-F hotkey brings up the 'Format disk’ dialog. + +Workabout System Screen + +The Psion-F hotkey brings up the 'Format disk’ dialog. + + +Workabout Command Processor +The Psion-F hotkey brings up the 'Set date and time formats’ dialog. + + +APPENDIX C - MENU DIFFERENCES + + +Shift-Psion-F Number formats/Time and date format +Psion Series 3a/3c and Siena System Screen + +The Shift-Psion-F hotkey brings up the 'Set number formats’ dialog. + +Workabout System Screen + +The Shift-Psion-F hotkey brings up the 'Set date and time formats’ dialog. + +Workabout Command Processor + +The Shift-Psion-F hotkey does nothing. + + +Psion-G Create new group +Psion Series 3a/3c and Siena System Screen +The Psion-G hotkey brings up the 'Create new group’ dialog. + + +Workabout System Screen + + +The Psion-G hotkey does nothing. New application groups cannot be created on the Workabout. + + +Psion-K Disc info/Toggle keyboard +Psion Series 3a/3c and Siena System Screen + +The Psion-K brings up the 'Disk info’ window. + +Workabout System Screen + +The Psion-K brings up the 'Disk info’ window. + +Workabout Command Processor + + +The Psion-K hotkey toggles between ‘Standard keyboard' and 'Special keyboard’. The text for this option +in the associated menu changes accordingly. + + +Shift-Psion-N Give 'Normal' system screen + + +Psion Series 3a/3c and Siena System Screen + + +The Shift-Psion-N hotkey switches the System Screen to 'Normal' mode without the 'Memory used' bar at +the bottom. + + +Workabout System Screen and Command Processor +Shift-Psion-N does nothing. + + +Shift-Psion-M Give 'Memory' system screen + + +Psion Series 3a/3c and Siena System Screen + + +The Shift-Psion-M hotkey switches the System Screen to 'Memory' mode with the 'Memory used" bar +displayed at the bottom. + + +Workabout System Screen and Command Processor +Shift-Psion-M does nothing. + + +Psion-O Auto switch off +Psion Series 3a/3c and Siena System Screen + +The Psion-O hotkey brings up the 'Set auto switch off times’ dialog. + +Workabout System Screen and Command Processor + + +Psion-O does nothing, (Psion-A is used instead). + + +WORKABOUT PROGRAMMING GUIDE + + +Psion-P Set owner information +Psion Series 3a/3c and Siena System Screen + +The Psion-P hotkey brings up the 'Set owner information’ dialog. + +Workabout System Screen + +The Psion-P hotkey does nothing. + + +Psion-S Set the sound +Psion Series 3a/3c and Siena System Screen + +The Psion-S hotkey brings up the 'Set the sound’ dialog. + +Workabout System Screen + +The Psion-S hotkey brings up the 'Set the sound’ dialog. + + +The ‘Alarm sounds' option is not present because the Workabout does not have digital sound capabilities, +unlike the Series 3a/3c. + + +Time:Psion-S/Shift-Psion-S Set summer time +Psion Series 3a/3c and Siena System Screen + +To set the summer time on/off the hotkey is Psion-S within the Time application. + +The Shift-Psion-S hotkey does nothing. + +Workabout System Screen + +To set the summer time on/off the hotkey is Shift-Psion-S (there is no Time application). + +Workabout Command Processor + +The Shift-Psion-S hotkey brings up the 'Set summer time’ dialog. + + +Psion-T Set file attributes/Set time and date + + +Psion Series 3a/3c and Siena System Screen + + +The Psion-T hotkey brings up the 'Set file attributes’ dialog. (Note that the Psion-T hotkey brings up the +‘Set time and date’ dialog in the Time application.) + + +Workabout System Screen + + +There is no 'Set file attributes' option on the 'File' menu. The Psion-T hotkey brings up the 'Set time and +date’ dialog instead. + + +Workabout Command Processor +The Psion-T hotkey brings up the 'Set time and date’ dialog. + + +Psion-U Usage monitor/Update lists +Psion Series 3a/3c and Siena System Screen + +The Psion-U hotkey brings up the 'Usage monitor’ dialog. + +Workabout System Screen + +The Psion-U hotkey updates the lists of files displayed under each application icon. + + +Psion-V About Series 3a/3c/Versions + + +Psion Series 3a/3c and Siena System Screen + + +The Psion-V hotkey brings up the Series 3a/3c copyright screen, which shows the EPOC O/S version +number. + + +APPENDIX C - MENU DIFFERENCES + + +Workabout System Screen + + +The Psion-V hotkey brings up the 'Software versions’ window, which shows the ROM version number, the +date and time the ROM was mastered, and the EPOC O/S version. + + +Shift-Psion-V About application +Psion Series 3a/3c and Siena System Screen + + +The Shift-Psion-V hotkey brings up the 'About"Application_name" window for the currently highlighted +application (with the name "Application_name"). + + +Workabout System Screen +The Shift-Psion-V hotkey does nothing. + + +Psion-W Password/Toggle wrap +Psion Series 3a/3c and Siena System Screen + +The Psion-W hotkey brings up the 'Set password’ dialog. + +Workabout System Screen + +The Psion-W hotkey does nothing. A system password cannot be set on the Workabout. + +Workabout Command Processor + + +The Psion-W hotkey toggles between 'Wrap on' and 'Wrap off. Word wrap is only applicable to the +Workabout's restricted screen within the Command Processor. + + +Psion-X Exit +Psion Series 3a/3c and Siena System Screen + + +The Psion-X hotkey does nothing in the System Screen. The system Screen cannot be exited and is always +a running process. + + +Workabout System Screen + + +The Psion-X hotkey brings up the 'Exit System Screen’ dialog. The System Screen can be exited, since +there is always at least one other process running (the Startup Shell). + + +Psion-Y Printer +Psion Series 3a/3c and Siena System Screen + +The Psion-Y hotkey brings up the 'Printer configuration’ window. + +Workabout System Screen + +The Psion-Y hotkey does nothing. + + +Psion-Diamond/Psion-Space Caps lock on/off +Psion Series 3a/3c and Siena System Screen + +The Psion-Diamond hotkey switches Caps Lock on and off. + +Workabout System Screen and Command Processor + + +The Psion-Space hotkey switches Caps Lock on and off, (there is no Diamond key). this is actually +implemented in the Startup Shell process which runs in the background, so it applies to any application. + + +Psion-Tab/Shift-Psion-Tab Display full path in file-related dialogs +Psion Series 3a/3c and Siena System Screen +To display the full path in file-related dialogs, Psion-Tab or Shift-Psion-Tab may be pressed. + + +WORKABOUT PROGRAMMING GUIDE + + +Workabout System Screen and Command Processor +To display the full path in file-related dialogs, Shift-Psion-Tab must be pressed. + + +Psion-Tab is used for task switching - see below. + + +Psion-+ / Psion-> Make directory +Psion Series 3a/3c System Screen + +The Psion-+ hotkey brings up the ‘Make directory’ dialog. + +Workabout System Screen +The Psion-+ hotkey brings up the ‘Make directory’ dialog. + + +Siena System Screen + + +The Psion-> hotkey brings up the ‘Make directory’ dialog, (Psion-+ only available via numeric keypad). + + +Psion-- / Psion-< Remove directory +Psion Series 3a/3c System Screen + +The Psion-- hotkey brings up the ‘Remove directory’ dialog. + +Workabout System Screen + +The Psion-- hotkey brings up the ‘Remove directory’ dialog. + +Siena System Screen + + +The Psion-< hotkey brings up the ‘Remove directory’ dialog, (Psion--, [Psion-Minus], is allocated to +“Remove application’). + + +Psion-/ / Psion-- Remove application + + +Psion Series 3a/3c System Screen + + +The Psion-/ hotkey brings up the ‘Remove “App” application’ dialog, where “App” is the currently +highlighted application. + + +Workabout System Screen + + +The Psion-/ hotkey brings up the ‘Remove “App” application’ dialog, where “App” is the currently +highlighted application. + + +Siena System Screen + + +The Psion-- hotkey (Psion-Minus) brings up the ‘Remove “App” application’ dialog, where “App” is the +currently highlighted application, (Psion-Fn-D would be too awkward). + + +Shift-Psion-O Control menu +Psion Series 3a/3c System Screen + +Does nothing. + +Psion Workabout System Screen + +Does nothing. + +Siena System Screen + + +The Psion-O hotkey brings up the ‘Control’ menu, (the screen is too narrow to fit this on the main menu +bar). + + +APPENDIX C - MENU DIFFERENCES + + +Switch task +Psion HC + + +TASK switches forwards one task. +SHIFT-TASK switches backwards one task. + + +Psion Series 3a/3c and Siena System Screen + + +Shift-System (icon button) switches forwards one task. +Shift-Psion-System switches backwards one task. + + +Psion Workabout System Screen and Command Processor + + +Psion-Tab is used for task switching (forwards only). +On the Series 3a/3c this accelerator is used to display the full path in file-related dialogs.. + + +On the Workabout Shift-Psion-Tab is used to display the full path in file-related dialogs, and does not +switch backwards one task. + + +SS —_____————____________________________ +Menus + + +Some menu options that are present on the Series 3a/3c and Siena System Screen are not present on the +Workabout System Screen, are on a different menu, or have a slightly different functionality. + + +File menu + +Psion Series 3a/3c and Siena System Screen + +Copy file Brings up the 'Copy file’ dialog, with 'Subdirectories' and "Modified only' choices + +File attributes Brings up the 'Set file attributes’ dialog. + +Backup files The 'File’ choice list allows 'All’ or Modified since last backup’. + +Psion Workabout System Screen + +Copy file Brings up the 'Copy file' dialog, which does not have 'Subdirectories' and 'Modified +only' choices, (restricted screen height). + +File attributes Not present. + +Backup files The 'File' choice list allows ‘All’ or 'Since last backup’, (shortened to fit in window). + +Disk menu + +Psion Series 3a/3c and Siena System Screen + +Default disk Brings up the 'Set default disk’ dialog. + +Psion Workabout System Screen + +Default disk Not present (this option is on the 'Control' menu). + +Apps menu + + +Psion Series 3a/3c and Siena System Screen + + +mt + + +Assign button Brings up the '"Assign button to "Icon_button" dialog, +where "Icon_button" is the name above one of the Series 3a/3c icon buttons. + + +Psion Workabout System Screen + + +Assign button Not present (there are no icon buttons on the Workabout). + + +WORKABOUT PROGRAMMING GUIDE + + +Info menu + + +The differences are: + + +Psion Series 3a/3c System Screen + + +Set owner +Disk info +Battery info +Usage monitor + + +About Series +3a/3c + + +About application + + +Versions + + +Brings up the 'Set owner information’ dialog. +Displays Disk A , Internal disk I and Disk B. +Brings up the 'Battery info' window. + +Brings up the 'Usage monitor’ dialog. + + +Brings up the Psion Series 3a/3c startup screen, giving the Epoc/OS version number +and copyright dates. + + +Brings up a window of information about the currently highlighted application. + + +Not present, (see 'About Series 3a/3c' above). + + +Psion Workabout System Screen + + +Update lists +Disk info + +Set owner +Battery info +Usage monitor + + +About Series +3a/3c + + +About application + + +Versions + + +(In the Series 3a/3c and Siena ‘Set preferences’ dialog) + +Displays Disk A , Internal disk I and Disk B. + +Not present. Owner details cannot be set on the Workabout. + +Not present. Battery information is obtained by pressing Shift-Ctrl-B. +Not present. There is no usage monitor on the Workabout. + + +Not present, (see 'Versions' below). + + +Not present. + + +The ‘Software versions' window is presented, giving the ROM version number, date +and time of mastering, and the Epoc/OS version number. This, along with the +copyright screen in the Startup Shell, replaces the 'About Series 3a/3c’ option of the +Series 3a/3c. + + +Psion Siena System Screen + + +Set owner +Disk info +Battery info +Usage monitor + + +About Siena + + +About application + + +Versions + + +Brings up the 'Set owner information’ dialog. + +Displays Disk A (external drive) and Internal disk I only. +Brings up the 'Battery info' window. + +Brings up the 'Usage monitor’ dialog. + + +Brings up the Psion Siena startup screen, giving the Epoc/OS version number and +copyright dates. + + +Brings up a window of information about the currently highlighted application. + + +Not present, (see ‘About Siena’ above). + + +Control menu + + +The differences are: + + +Psion Series 3a/3c System Screen + + +Sound +Printer + + +Auto switch off + + +Dialling + + +Brings up the 'Set the sound’ dialog, which includes an 'Alarm sounds' choice. +Brings up the 'Printer configuration’ dialog. + + +Brings up the 'Set auto switch of' dialog - there are no backlight choices for the Series +3a/3c where a backlight not present, (options present for backlit Series 3c variant). + + +Brings up the 'Dial settings’ dialog. + + +"Evaluate" +format + + +Number formats +Set time and date + + +Time and date +format + + +Status window + + +Default disk + + +APPENDIX C - MENU DIFFERENCES + + +Brings up the ‘Set "Evaluate" format’ dialog. + + +Brings up the 'Set number formats’ dialog. +Not present - set from the Time application. + + +Not present - set from the Time application. + + +Brings up the 'Status window display’ window - the 'Clock type’ can be Digital or +Analog. + + +Not present - this option is on the 'Control' menu.. + + +Psion Workabout System Screen + + +The name of this menu is abbreviated to 'Ctrl'. + + +Sound + + +Printer + + +Auto switch off + + +‘Dialling’ option + + +"Evaluate" +format + + +Number formats +Set time and date + + +Time and date +format + + +Status window + + +Default disk + + +Brings up the 'Set the sound’ dialog - there is no 'Alarm sounds' choice, (the +Workabout does not have digital sound capabilities). + + +Not present. + + +Brings up the 'Set auto switch of times' dialog, which has three choices for the +backlight. + + +Not present. + + +Not present - moved to the 'Set preferences’ option of the 'Special' menu. + + +Not present - moved to the 'Set preferences’ option of the ‘Special’ menu.. +Brings up the 'Set time and date dialog’. + + +Brings up the 'Set time and date dialog’. + + +Brings up the 'Status window display’ window - there is no 'Clock type’ choice (only a +Digital clock is allowed). + + +Brings up the 'Set default disk’ dialog. + + +Psion Workabout Command Processor + + +This menu contains ‘Sound’, 'Auto switch off and ‘Special keyboard’ options only. The 'Special keyboard' +option is implemented as a choice in the 'Preferences' option of the 'Spec' menu in the Workabout System + + +Screen. + + +Psion Siena System Screen + + +Accessed from the ‘Special’ menu by using the ‘Control...’ option. + + +Sound +Printer + + +Auto switch off + + +Dialling + + +"Evaluate" +format + + +Number formats +Set time and date + + +Time and date +format + + +Brings up the 'Set the sound’ dialog, which includes an 'Alarm sounds' choice. +Brings up the 'Printer configuration’ dialog. + + +Brings up the 'Set auto switch of' dialog - there are no backlight choices for the Siena +(a backlight is not present). + + +Not present - the Siena has a piezo buzzer, not a speaker. + + +Brings up the 'Set "Evaluate" format’ dialog. + + +Brings up the 'Set number formats’ dialog. +Not present - set from the Time application. + + +Not present - set from the Time application. + + +WORKABOUT PROGRAMMING GUIDE + + +Info window + + +Default disk + + +Brings up the 'Info window display’ window - there are no 'Clock type’ or ‘Disk +indicators’ options because the Info window is too narrow, (it is otherwise identical to +the Series 3a/3c Status window). + + +Not present - this option is on the 'Control' menu.. + + +Special menu + + +The differences are: + + +Psion Series 3a/3c System Screen + + +Set preferences +Password +Remote link / +Communications + + +Tips + + +Exit + + +Brings up the 'Set preferences’ dialog, which includes an ‘Update lists' choice. +Brings up the 'Set password' dialog. + + +Brings up the 'Remote link’ dialog - there is no 'Port' choice since the Series 3a/3c +only has one port. (Note that the option is called Communications on the Series 3c +and there is a ‘Power setting’ option, for Low and High Infrared power levels.). + + +On Series 3c only - to control whether a Tip is displayed when the machine is +switched on. + + +Not present - the system Screen cannot be exited and is always a running process. + + +Psion Workabout System Screen + + +The name of this menu is abbreviated to ‘Spec’. + + +Set preferences + + +Password + + +Remote link + + +Create new group +Tips + + +Exit + + +Brings up the 'Set preferences’ dialog, which does not include an ‘Update lists' +choice, but has the "Number formats’ and '"Evaluate" format’ choices (on the Control +menu of the Series 3a/3c and Siena), plus a 'keyboard' choice to swap between +Standard and Special keyboards. + + +Not present - you cannot set a system password on the Workabout. + + +Brings up the 'Remote link’ dialog - there is a 'Port' choice since the Workabout can +be fitted with several ports. (Note that there is no ‘Power setting’ option, because +there is no Infrared communications. ) + + +Not present - you cannot create groups on the Workabout. +Not present. + + +Brings up the 'Exit System Screen' dialog. The System Screen can be exited, since +there is always at least one other process running (the Startup Shell). + + +Psion Workabout Command Processor + + +This menu contains 'Remote link’, 'Wrap on/off’, 'Zoom in’, "Zoom out’ and 'Exit' options only. The "Wrap +on/off option is not implemented anywhere in the Workabout System Screen menus. Because it toggles +word wrap on and off, the text for this option changes from 'Wrap on' to 'Wrap off accordingly. + + +Psion Siena System Screen + + +Control... +Set preferences +Password + + +Communications + + +Tips + + +Exit + + +Brings up the Control menu, (which is not present on the menu bar). +Brings up the 'Set preferences’ dialog, which includes an 'Update lists' choice. +Brings up the 'Set password' dialog. + + +Brings up the ‘Communications’ dialog - there is no 'Port' choice since the Siena only +has one port. There is a ‘Power setting’ option, for Low and High Infrared power +levels. (Note that the option is called ‘Remote link’ on the Series 3a and Workabout.) + + +To control whether a Tip is displayed when the machine is switched on. + + +Not present - the system Screen cannot be exited and is always a running process. + + +APPENDIX C - MENU DIFFERENCES + + +‘Diamond’ menu + + +The differences are: + +Psion Series 3a/3c and Siena System Screen + +Normal Switches the System Screen to not show the 'Memory used' bar at the bottom. +Memory Switches the System Screen to show the 'Memory used' bar at the bottom. + + +Psion Workabout System Screen + + +This menu is not present, (there is no Diamond key, and the screen is of restricted height). + + +Time menu + + +The differences are: + + +Psion Series 3a/3c and Siena System Screen + + +This menu is not present. The "Time and date’, ‘Summer times' and 'Formats' options are in the menus for +the Time application. + + +Psion Workabout System Screen + + +This menu is not present. The 'Set time and date’ and 'Time and date format’ options are in the 'Ctrl' +menu. 'Summer time' is incorporated as a choice in the 'Set time and date’ dialog. + + +Psion Workabout Command Processor + + +This menu contains "Time and date’, ‘Summer time’ and 'Formats' options. + + +INDEX + + +.btf files +Workabout, 1-2 +add files +Workabout, 2-7 +APPEND +command differences - HC - Workabout +and MS-DOS, B-3 +applications +differences in SIBO systems, C-1 +Apps menu +Series 3a/c and Siena System Screen, C-7 +asynchronous programs +Workabout, 3-4 +ATTRIB +Workabout command, 3-9 +ATTRIB{UTE} +command differences - HC - Workabout +and MS-DOS, B-3 +AUTO +command differences - HC - Workabout +and MS-DOS, B-4 +autoexec file +Workabout, 2-5 +autoexec. btf +Workabout, 1-2 +backlight +differences in SIBO systems, C-1 +BACKLIGHT +command differences - HC - Workabout +and MS-DOS, B-4 +BACKUP +command differences - HC - Workabout +and MS-DOS, B-4 +bar code reader +conversion of HC reader for Workabout, +A-5 +batch file processing +Workabout, 3-3 +batch files + + +command processor - HC - Workabout and + + +MS-DOS, B-2 +BATCHK +command differences - HC - Workabout +and MS-DOS, B-4 +BATTERY +command differences - HC - Workabout +and MS-DOS, B-5 +battery pack +Workabout docking station slot, 1-4 +BREAK +command differences - HC - Workabout +and MS-DOS, B-5 + + +buzzer +Workabout, 1-8 +C$P$ +environment variable Workabout, 2-11 +C$P@ +environment variable Workabout, 2-10 +C$PE£ +environment variable Workabout, 2-11 +C$PA to C$PZ +environment variable Workabout, 2-11 +CALC +command differences - HC - Workabout +and MS-DOS, B-5 +Workabout command, 3-9 +CALL +command differences - HC - Workabout +and MS-DOS, B-5 +Workabout command, 3-9 +CD +command differences - HC - Workabout +and MS-DOS, B-6 +Workabout command, 3-10 +CHCP +command differences - HC - Workabout +and MS-DOS, B-6 +CHDIR +command differences - HC - Workabout +and MS-DOS, B-6 +Workabout command, 3-10 +CHKDSK +command differences - HC - Workabout +and MS-DOS, B-7 +CHOICE +command differences - HC - Workabout +and MS-DOS, B-7 +clocks +differences in SIBO systems, C-1 +CLS +command differences - HC - Workabout +and MS-DOS, B-7 +Workabout command, 3-10 +cold reset +Workabout, 1-10 +COMMAND +command differences - HC - Workabout +and MS-DOS, B-7 +command line editor +Workabout, 3-5 +command processor +alphabetic listing Workabout, 3-8 + + +batch files - HC - Workabout and MS-DOS, + + +B-2 + +commands - HC - Workabout and MS- +DOS, B-1 + +differences - HC - Workabout and MS- +DOS, B-1 + + +directories - HC - Workabout and MS-DOS, + + +B-2 + + +file and directory names - HC - Workabout + + +and MS-DOS, B-2 + + +file name wildcards - HC - Workabout and + + +MS-DOS, B-2 +help - HC - Workabout and MS-DOS, B-1 + + +WORKABOUT PROGRAMMING GUIDE + + +launching programs - HC - Workabout and +MS-DOS, B-2 +memory resident programs - HC - +Workabout and MS-DOS, B-3 +syntax restrictions Workabout, 3-8 +Workabout, 1-2, 1-9, 3-1 +command processor menus +Workabout, 3-1 +command shell +see also command processor, B-1 +command syntax +Workabout, 3-8 +commands +command processor - HC - Workabout and +MS-DOS, B-1 +COMMS +command differences - HC - Workabout +and MS-DOS, B-8 +Workabout command, 3-10 +communications ports +Workabout, 1-4 +COMP +command differences - HC - Workabout +and MS-DOS, B-8 +CONFIG +command differences - HC - Workabout +and MS-DOS, B-8 +connecting +Workabout, 1-11 +Workabout hardware, 1-11 +Workabout software, 1-11 +Control menu +Series 3a/c System Screen, C-8 +Siena System Screen, C-9 +Workabout Command Processor, C-9 +Workabout System Screen, C-9 +COPY +command differences - HC - Workabout +and MS-DOS, B-8 +Workabout command, 3-11 +COUNTRY +command differences - HC - Workabout +and MS-DOS, B-9 +cradle +docking station Workabout, 1-4 +CTTY +command differences - HC - Workabout +and MS-DOS, B-9 +customising +Workabout, 1-10 +Workabout hardware, 1-10 +Workabout software, 1-11 +D +command differences - HC - Workabout +and MS-DOS, B-9 +DATA +command differences - HC - Workabout +and MS-DOS, B-9 +Workabout command, 3-11 +data integrity +Workabout, 2-6 +DATE +command differences - HC - Workabout +and MS-DOS, B-10 + + +Workabout command, 3-12 +DBLSPACE +command differences - HC - Workabout +and MS-DOS, B-10 +DEBUG +command differences - HC - Workabout +and MS-DOS, B-11 +DEFRAG +command differences - HC - Workabout +and MS-DOS, B-11 +DEL +Workabout command, 3-12 +DEL[ETE] +command differences - HC - Workabout +and MS-DOS, B-11 +DELTREE +command differences - HC - Workabout +and MS-DOS, B-12 +DEVICE +command differences - HC - Workabout +and MS-DOS, B-12 +Diamond menu +Series 3a/c and Siena System Screen, C-11 +DIR +command differences - HC - Workabout +and MS-DOS, B-12 +Workabout command, 3-12 +directories +command processor - HC - Workabout and +MS-DOS, B-2 +directory current +Workabout, 3-6 +Disk menu +Series 3a/c and Siena System Screen, C-7 +DISKCOMP +command differences - HC - Workabout +and MS-DOS, B-13 +DISKCOPY +command differences - HC - Workabout +and MS-DOS, B-13 +docking station +Workabout, 1-4 +Workabout specification, A-10 +DOSKEY +command differences - HC - Workabout +and MS-DOS, B-13 +DOSSHELL +command differences - HC - Workabout +and MS-DOS, B-13 +ECHO +command differences - HC - Workabout +and MS-DOS, B-14 +Workabout command, 3-13 +EDIT +command differences - HC - Workabout +and MS-DOS, B-14 +Workabout command, 3-13 +EMM386 +command differences - HC - Workabout +and MS-DOS, B-14 +ENV +command differences - HC - Workabout +and MS-DOS, B-14 +environment variable + + +C$P$ - Workabout, 2-11 +C$P@ - Workabout, 2-10 +C$PE£ - Workabout, 2-11 +C$PA to C$PZ - Workabout, 2-11 +S$SVER - Workabout, 2-10 +Workabout specific, 2-10 + +ERASE +command differences - HC - Workabout +and MS-DOS, B-15 +Workabout command, 3-14 + +ERRLEVEL +command differences - HC - Workabout +and MS-DOS, B-15 +Workabout command, 3-14 + +ERRORLEVEL +keyword - command processor, B-15 +keyword differences - HC - Workabout and +MS-DOS, B-15 + +events +Workabout, 2-2 + +EXIT +command differences - HC - Workabout +and MS-DOS, B-16 +Workabout command, 3-14 + +EXPAND +command differences - HC - Workabout +and MS-DOS, B-16 + +expansion ports +Workabout, 1-3 + +FASTHELP +command differences - HC - Workabout +and MS-DOS, B-16 + +FASTOPEN +command differences - HC - Workabout +and MS-DOS, B-17 + +FC +command differences - HC - Workabout +and MS-DOS, B-17 + +FCBS +command differences - HC - Workabout +and MS-DOS, B-17 + +FDISK +command differences - HC - Workabout +and MS-DOS, B-17 + +file and directory names +command processor - HC - Workabout and +MS-DOS, B-2 + +file in use error +Workabout, 3-6 + +File menu +Series 3a/c and Siena System Screen, C-7 + +file name wildcards +command processor - HC - Workabout and +MS-DOS, B-2 + +file names +Workabout command line, 3-7 + +file specification wildcards +Workabout, 3-8 + +FILES +command differences - HC - Workabout +and MS-DOS, B-18 +Workabout command, 3-14 + +files and directories +Workabout, 3-6 + + +INDEX + + +FIND +command differences - HC - Workabout +and MS-DOS, B-18 +fonts +Workabout, 1-9 +Workabout sizes, 3-2 +FOR +command differences - HC - Workabout +and MS-DOS, B-18 +Workabout command, 3-15 +FORMAT +command differences - HC - Workabout +and MS-DOS, B-18 +Workabout command, 3-15 +FREE +command differences - HC - Workabout +and MS-DOS, B-19 +fuse +Workabout, 1-6 +GOTO +command differences - HC - Workabout +and MS-DOS, B-19 +Workabout command, 3-15 +GRAPHICS +command differences - HC - Workabout +and MS-DOS, B-19 +hard reset +Workabout, 1-10 +hardware interrupts +Workabout, 3-21 +HC bar code reader +conversion to Workabout connector, A-5 +help +command processor - HC - Workabout and +MS-DOS, B-1 +HELP +command differences - HC - Workabout +and MS-DOS, B-19 +Workabout command, 3-15 +hot keys +differences in SIBO systems, C-2 +icons +differences in SIBO systems, C-1 +IF +command differences - HC - Workabout +and MS-DOS, B-20 +Workabout command, 3-16 +Info menu +Series 3a/c System Screen, C-8 +Siena System Screen, C-8 +Workabout System Screen, C-8 +INSTALL +command differences - HC - Workabout +and MS-DOS, B-20 +INTERLNK +command differences - HC - Workabout +and MS-DOS, B-20 +interrupts hardware +Workabout, 3-21 +INTERSVR +command differences - HC - Workabout +and MS-DOS, B-20 +key +Backlight Workabout, 1-7 + + +iii + + +WORKABOUT PROGRAMMING GUIDE + + +Contrast Workabout, 1-8 +Del Workabout, 1-8 +Enter Workabout, 1-8 +Menu Workabout, 1-7 +Off Workabout, 1-1, 1-7 +On/Esc Workabout, 1-1, 1-7 +Psion Workabout, 1-8 +key combination +Ctrl-Esc Workabout, 1-8 +Psion-Down Workabout, 1-8 +Psion-Left Workabout, 1-8 +Psion-Right Workabout, 1-8 +Psion-Space Workabout, 1-8 +Psion-Tab Workabout, 1-8 +Psion-Up Workabout, 1-8 +Shift-Ctrl-B Workabout, 1-8 +Shift-Esc Workabout, 1-8 +key Psion +Workabout, 1-7 +KEYB +command differences - HC - Workabout +and MS-DOS, B-21 +keyboard +Workabout, 1-7 +keyboards +differences in SIBO systems, C-1 +keys special +Workabout, 1-7 +Workabout batch file processing, 3-5 +Workabout command line editor, 3-5 +Keyword +ERRORLEVEL, B-15 +KILL +command differences - HC - Workabout +and MS-DOS, B-21 +Workabout command, 3-16 +LABEL +command differences - HC - Workabout +and MS-DOS, B-21 +Workabout command, 3-16 +launching programs + + +command processor - HC - Workabout and + + +MS-DOS, B-2 + +LCD display +Workabout, 1-6 + +LDEV +command differences - HC - Workabout +and MS-DOS, B-21 + +LH +command differences - HC - Workabout +and MS-DOS, B-22 + +LINK +Workabout command, 3-17 + +lithium battery +Workabout, 1-6 + +LLDEV +command differences - HC - Workabout +and MS-DOS, B-22 +Workabout command, 3-17 + +LOADFIX +command differences - HC - Workabout +and MS-DOS, B-22 + + +LOADHIGH +command differences - HC - Workabout +and MS-DOS, B-22 +LOWBAT +command differences - HC - Workabout +and MS-DOS, B-23 +LPDEV +command differences - HC - Workabout +and MS-DOS, B-23 +Workabout command, 3-18 +LPROC +command differences - HC - Workabout +and MS-DOS, B-23 +Workabout command, 3-18 +LSEG +command differences - HC - Workabout +and MS-DOS, B-23 +Workabout command, 3-19 +MASTER +command differences - HC - Workabout +and MS-DOS, B-24 +MD +command differences - HC - Workabout +and MS-DOS, B-24 +Workabout command, 3-20 +MEM +command differences - HC - Workabout +and MS-DOS, B-24 +Workabout command, 3-20 +MEMMAKER +command differences - HC - Workabout +and MS-DOS, B-24 +memory resident programs + + +command processor - HC - Workabout and + + +MS-DOS, B-3 +menu accelerators +differences in SIBO systems, C-2 +menu names +differences in SIBO systems, C-1 +menu options +differences in SIBO systems, C-1 +MENUCOLOR +command differences - HC - Workabout +and MS-DOS, B-25 +MENUDEFAULT +command differences - HC - Workabout +and MS-DOS, B-25 +MENUITEM +command differences - HC - Workabout +and MS-DOS, B-25 +MKDIR +command differences - HC - Workabout +and MS-DOS, B-25 +Workabout command, 3-20 +MODE +command differences - HC - Workabout +and MS-DOS, B-26 +MORE +command differences - HC - Workabout +and MS-DOS, B-26 +mounting bracket +VIC (Vehicle Interface Cradle), A-8 + + +MOVE +command differences - HC - Workabout +and MS-DOS, B-26 +MSAV +command differences - HC - Workabout +and MS-DOS, B-26 +MSBACKUP +command differences - HC - Workabout +and MS-DOS, B-27 +MSCDEX +command differences - HC - Workabout +and MS-DOS, B-27 +MSD +command differences - HC - Workabout +and MS-DOS, B-27 +NLSFUNC +command differences - HC - Workabout +and MS-DOS, B-27 +NOTIFY +command differences - HC - Workabout +and MS-DOS, B-27 +NUMLOCK +command differences - HC - Workabout +and MS-DOS, B-28 +OFFENABLE +command differences - HC - Workabout +and MS-DOS, B-28 +opl.dyl +Workabout, 1-9 +oplts3.dyl +Workabout, 1-9 +path +Workabout command line, 3-7 +PATH +command differences - HC - Workabout +and MS-DOS, B-28 +path default +Workabout, 3-6 +PAUSE +command differences - HC - Workabout +and MS-DOS, B-28 +Workabout command, 3-20 +pausing screen display +Workabout, 3-6 +ports +communications Workabout, 1-4 +differences in SIBO systems, C-1 +Workabout expansion, 1-3 +POWER +command differences - HC - Workabout +and MS-DOS, B-29 +PRINT +command differences - HC - Workabout +and MS-DOS, B-29 +processor Workabout +NEC V30H, 1-3 +program launching +Workabout, 3-3 +programming +Workabout, 2-1 +programming choices +Workabout, 2-1 +programming examples +Lcdtest Workabout, 2-10 + + +INDEX + + +Tables Workabout, 2-8 +Workabout, 2-8 +programming guidelines +Workabout, 2-6 +programs asynchronous +Workabout, 3-4 +programs synchronous +Workabout, 3-4 +programs terminating +Workabout, 3-4 +PROMPT +command differences - HC - Workabout +and MS-DOS, B-29 +Psion-- hotkey +S3a/c, C-6 +Siena System Screen, C-6 +Workabout System Screen, C-6 +Psion key +Workabout, 1-7 +Psion-/ hotkey +S3a/c, C-6 +Workabout System Screen, C-6 +Psion-+ hotkey +S3a/c, C-6 +Workabout System Screen, C-6 +Psion-< hotkey +Siena System Screen, C-6 +Psion-> hotkey +Siena System Screen, C-6 +Psion-A hotkey +S3a/c and Siena System Screen, C-2 +Workabout System Screen, C-2 +Psion-B hotkey +S3a/c and Siena System Screen, C-2 +Psion-Ctrl-Del +Workabout, 1-10 +Psion-Diamond hotkey +S3a/c and Siena System Screen, C-5 +Psion-F hotkey +S3a/c and Siena System Screen, C-2 +Workabout Command Processor, C-2 +Psion-G hotkey +S3a/c and Siena System Screen, C-3 +Psion-K hotkey +S3a/c and Siena System Screen, C-3 +Workabout Command Processor, C-3 +Workabout System Screen, C-3 +Psion-O hotkey +S3a/c and Siena System Screen, C-3 +Psion-S hotkey +S3a/c and Siena System Screen, C-4 +Workabout System Screen, C-4 +Psion-Shift-Ctrl-Del +Workabout, 1-10 +Psion-Space hotkey +Workabout System Screen and Command +Processor, C-5 +Psion-T hotkey +S3a/c and Siena System Screen, C-4 +Workabout Command Processor, C-4 +Psion-Tab hotkey +S3a/c and Siena System Screen, C-5 +Workabout System Screen and Command +Processor, C-7 + + +WORKABOUT PROGRAMMING GUIDE + + +Psion-U hotkey +S3a/c and Siena System Screen, C-4 +Workabout System Screen, C-4 +Psion-V hotkey +S3a/c and Siena System Screen, C-4 +Workabout System Screen, C-5 +Psion-W hotkey +S3a/c and Siena System Screen, C-5 +Workabout Command Processor, C-5 +Psion-X hotkey +Workabout System Screen, C-5 +Psion-Y hotkey +S3a/c and Siena System Screen, C-5 +QBASIC +command differences - HC - Workabout +and MS-DOS, B-29 +QUIT +command differences - HC - Workabout +and MS-DOS, B-29 +Workabout command, 3-20 +RD +command differences - HC - Workabout +and MS-DOS, B-30 +Workabout command, 3-21 +REASON +command differences - HC - Workabout +and MS-DOS, B-30 +Workabout command, 3-21 +REM +command differences - HC - Workabout +and MS-DOS, B-30 +Workabout command, 3-21 +REN +command differences - HC - Workabout +and MS-DOS, B-30 +Workabout command, 3-22 +REPLACE +command differences - HC - Workabout +and MS-DOS, B-31 +reset cold +Workabout, 1-10 +reset hard +Workabout, 1-10 +reset soft +Workabout, 1-10 +RESTORE +command differences - HC - Workabout +and MS-DOS, B-31 +RESUME +command differences - HC - Workabout +and MS-DOS, B-31 +RMDIR +command differences - HC - Workabout +and MS-DOS, B-31 +Workabout command, 3-22 +ROM components +Workabout, 1-9 +RS232 / bar code interface module +specification, A-4 +RS232 / RS232 TTL interface module +specification, A-3 +running programs +Workabout, 3-3 + + +S$SVER +environment variable Workabout, 2-10 +SCANDISK +command differences - HC - Workabout +and MS-DOS, B-31 +screen +Workabout, 1-6 +screen display pausing +Workabout, 3-6 +serial numbers +Workabout, A-2 +Series 3a/c and Workabout +system screen differences, C-1 +SET +command differences - HC - Workabout +and MS-DOS, B-32 +Workabout command, 3-22 +SETDATE +command differences - HC - Workabout +and MS-DOS, B-32 +SETDEF +command differences - HC - Workabout +and MS-DOS, B-32 +SETVER +command differences - HC - Workabout +and MS-DOS, B-33 +SHARE +command differences - HC - Workabout +and MS-DOS, B-33 +SHEET +Workabout command, 3-24 +SHELL +command differences - HC - Workabout +and MS-DOS, B-33 +shell replacing +Workabout, 2-4 +SHIFT +command differences - HC - Workabout +and MS-DOS, B-33 +Workabout command, 3-24 +Shift-Psion-D hotkey +S3a/c and Siena System Screen, C-2 +Shift-Psion-E hotkey +S3a/c and Siena System Screen, C-2 +Shift-Psion-F hotkey +S3a/c and Siena System Screen, C-3 +Workabout System Screen, C-3 +Shift-Psion-M hotkey +S3a/c and Siena System Screen, C-3 +Shift-Psion-N hotkey +S3a/c and Siena System Screen, C-3 +Shift-Psion-O hotkey +Siena System Screen, C-6 +Shift-Psion-S hotkey +Workabout CommandProcessor, C-4 +Workabout System Screen, C-4 +Shift-Psion-System hotkey +S3a/c and Siena System Screen, C-7 +Shift-Psion-Tab hotkey +S3a/c and Siena System Screen, C-5 +Workabout System Screen and Command +Processor, C-6 +Shift-Psion-V hotkey +S3a/c and Siena System Screen, C-5 + + +Shift-System hotkey +S3a/c and Siena System Screen, C-7 +SHIFT-TASK hotkey +HC, C-7 +SMARTDRV +command differences - HC - Workabout +and MS-DOS, B-34 +soft reset +Workabout, 1-10 +software customisation +Workabout, 2-3 +SORT +command differences - HC - Workabout +and MS-DOS, B-34 +sound +differences in SIBO systems, C-1 +Workabout, 1-8 +Special menu +Series 3a/c System Screen, C-10 +Siena System Screen, C-10 +Workabout Command Processor, C-10 +Workabout System Screen, C-10 +specification technical +docking station Workabout, A-10 +RS232 / bar code interface module, A-4 +RS232 / RS232 TTL interface module, A-3 +Vehicle Interface Cradle (VIC), A-5 +VIC (1 port and vehicle power option), A-7 +VIC (3 port and vehicle power option), A-6 +VIC conventional 9-Pin RS232 serial ports, +A-9 +VIC extended 15-way RS232 serial port, +A-9 +VIC mounting bracket, A-8 +VIC Psion LIF connector, A-9 +VIC vehicle power input connector, A-8 +Workabout, A-1 +SSD drives +Workabout, 1-3 +START +command differences - HC - Workabout +and MS-DOS, B-34 +Workabout command, 3-25 +start up SSD +Workabout, 1-2 +startup shell +Workabout, 1-2, 2-3 +STOP +command differences - HC - Workabout +and MS-DOS, B-34 +Workabout command, 3-25 +SUBMENU +command differences - HC - Workabout +and MS-DOS, B-35 +SUBST +command differences - HC - Workabout +and MS-DOS, B-35 +SUSPEND +command differences - HC - Workabout +and MS-DOS, B-35 +Switch task +key press, C-7 +synchronous programs +Workabout, 3-4 + + +INDEX + + +SYS +command differences - HC - Workabout +and MS-DOS, B-35 +sys$cmdp.img +Workabout, 1-9, 2-4 +sys$ctry.cfo +Workabout, 1-9 +sys$ctry.int +Workabout, 1-9 +sys$gsys.cmdp +Workabout, 1-9 +sys$gsys.img +Workabout, 2-4 +sys$shll.img +Workabout, 1-9, 2-3, 2-4 +sys$wsrv.img +Workabout, 2-3 +system interfaces multiple +Workabout, 3-6 +system screen +adding applications Workabout, 2-4 +differences Series 3a/c and Workabout, C-1 +differences Workabout and Series 3a/c, C-1 +replacing Workabout, 2-4 +Workabout, 1-2, 1-9 +TASK hotkey +HC, C-7 +Task switch +forwards +Series 3a/c and Siena, C-7 + + +Task switch backwards +HC, C-7 +Series 3a/c and Siena System Screen, C-7 +Task switch forwards +HC, C-7 +Workabout System Screen and Command +Processor, C-7 +TERMINATE +command differences - HC - Workabout +and MS-DOS, B-35 +TIME +command differences - HC - Workabout +and MS-DOS, B-36 +Workabout command, 3-25 +Time menu +Series 3a/c and Siena System Screen, C-11 +Workabout Command Processor, C-11 +Workabout System Screen, C-11 +TREE +command differences - HC - Workabout +and MS-DOS, B-36 +TYPE +command differences - HC - Workabout +and MS-DOS, B-36 +Workabout command, 3-26 +UNDELETE +command differences - HC - Workabout +and MS-DOS, B-36 +UNFORMAT +command differences - HC - Workabout +and MS-DOS, B-37 +user interface +Workabout, 2-2 + + +WORKABOUT PROGRAMMING GUIDE + + +Vehicle Interface Cradle (VIC) +specification, A-5 +VER +command differences - HC - Workabout +and MS-DOS, B-37 +Workabout command, 3-26 +VERIFY +command differences - HC - Workabout +and MS-DOS, B-37 +VIC (Vehicle Interface Cradle) +1 port and vehicle power option, A-7 +3 port and vehicle power option, A-6 + + +conventional 9-Pin RS232 serial ports, A-9 + + +extended 15-way RS232 serial port, A-9 +mounting bracket, A-8 +Psion LIF Connector, A-9 +specification, A-5 +vehicle power input connector, A-8 +VOL +command differences - HC - Workabout +and MS-DOS, B-37 +Workabout command, 3-26 +VSAFE +command differences - HC - Workabout +and MS-DOS, B-38 +WAIT +command differences - HC - Workabout +and MS-DOS, B-38 +Workabout command, 3-26 +wildcards +in Workabout file specification, 3-8 +window server +Workabout, 2-3 +WNOTIFY +command differences - HC - Workabout +and MS-DOS, B-38 +Workabout +add files, 2-7 +adding system screen applications, 2-4 +ALM no access, 2-7 +autoexec file, 2-5 +autoexec.btf, 1-2 +basic hardware, 1-2 +basic software, 1-8 +batch file processing, 3-3 +clock rate, 1-3 +cold reset, 1-10 +command line editor, 3-5 +command processor, 1-2, 1-9, 3-1 +command processor menus, 3-1 +command syntax, 3-8 +command syntax restrictions, 3-8 +commands alphabetic listing, 3-8 +communications ports, 1-4 +connecting, 1-11 +connecting hardware, 1-11 +connecting software, 1-11 +customising, 1-10 +customising hardware, 1-10 +customising software, 1-11 +data integrity, 2-6 +directory current, 3-6 +docking station (Cradle), 1-4 +docking station battery pack slot, 1-4 + + +viii + + +environment variables - specific, 2-10 +events, 2-2 + +file in use error, 3-6 + +file names in command line, 3-7 +files and directories, 3-6 + +font sizes, 3-2 + +fonts, 1-9 + +fuse, 1-6 + +hard reset, 1-10 + +hardware interrupts, 3-21 + +holster, 1-4 + +introduction to, 1-1 + +keyboard, 1-7 + +keys special, 1-7 + +lithium battery, 1-6 + +non system screen applications, 2-6 +opl.dyl, 1-9 + +oplts3.dyl, 1-9 + +path default, 3-6 + +path in command line, 3-7 +pausing screen display, 3-6 + +power supplies, 1-4 + +program launching, 3-3 +programming, 2-1 + +programming choices, 2-1 +programming examples, 2-8 +programming examples Lcdtest, 2-10 +programming examples tables, 2-8 +programming guidelines, 2-6 +programs asynchronous, 3-4 +programs synchronous, 3-4 + +RAM internal, 1-3 + +ROM, 1-3 + +ROM components, 1-9 + +screen, 1-6 + +serial numbers, A-2 + +soft reset, 1-10 + +software customisation, 2-3 +sound, 1-8 + +specification, A-1 + +SSDs, 1-3 + +start up SSD, 1-2 + +startup shell, 1-2, 2-3 +synchronous or asynchronous, 2-2 +sys$cmdp.img, 1-9, 2-4 +sys$ctry.cfo, 1-9 + +sys$ctry.int, 1-9 + +sys$gsys.cmdp, 1-9 + +sys$gsys.img, 2-4 + +sys$shll.img, 1-9, 2-3, 2-4 +sys$wsrv.img, 2-3 + +system interfaces multiple, 3-6 +system screen, 1-2, 1-9 +terminating programs, 3-4 + +user interface, 2-2 + +wildcards in file specification, 3-8 +WLD no access, 2-7 + + +Workabout and Series 3a/c + + +system screen differences, C-1 + + +Workabout bar code reader + + +conversion of old HC reader, A-5 + + +Workabout command + + +ATTRIB, 3-9 +CALC, 3-9 + + +INDEX + + +CALL, 3-9 + + +ERRLEVEL, 3-14 +EXIT, 3-14 +FILES, 3-14 +FOR, 3-15 +FORMAT, 3-15 +GOTO, 3-15 +HELP, 3-15 + +IF, 3-16 + +KILL, 3-16 +LABEL, 3-16 +LINK, 3-17 +LLDEV, 3-17 +LPDEV, 3-18 +LPROC, 3-18 +LSEG, 3-19 +MD, 3-20 +MEM, 3-20 +MKDIR, 3-20 +PAUSE, 3-20 + + +START, 3-25 +STOP, 3-25 +TIME, 3-25 +TYPE, 3-26 +VER, 3-26 +VOL, 3-26 +WAIT, 3-26 +Workabout command processor +differences from system screen, C-1 +Workabout Docking Station +specification, A-10 +Workabout processor +NEC V30H, 1-3 +Workabout special keys +batch file processing, 3-5 +command line editor, 3-5 +Workabout system screen +differences from command processor, C-1 +XCOPY +command differences - HC - Workabout +and MS-DOS, B-38 + + diff --git a/docs/1-05 EPOC OS System Services 2.30_djvu.txt b/docs/1-05 EPOC OS System Services 2.30_djvu.txt new file mode 100755 index 0000000..9ab2dd0 --- /dev/null +++ b/docs/1-05 EPOC OS System Services 2.30_djvu.txt @@ -0,0 +1,21059 @@ +SIBO 'C' Software Development Kit + + +EPOC O/S SYSTEM SERVICES + + +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 3s, Psion Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of +Psion PLC. + +Intel 8086 and 80286 are registered trademarks of Intel 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. Psion PLC acknowledges that some other names referred to are +registered trademarks. + + +CONTENTS + + +DTG OGuiC ts, isi eccci ss ce casisccctesecedeccsnccsstcsscodeccseecedesdecsdeccdececesssscedsccsnecstecdscedeccsssececedecedecessecestes Ld + + +SYSCEMM SEL VICES oi heh: suk veloeehs gcbedua vudewes saebeduh ods conte cebede pub coves cousvah edtbewstocebebenedtigweseeuhienonst +Single service:interrupts ::.43:8Ascniiao sss ob de adehl Adenine s Ag +Multi Service titerrupts's.esic.s3isstecstuts Seeeduveteossets Seeded sduvsesbaduesduysdeusteda dice dubsduectedsdyvadevednes dS +Gallin S COMVENHONS .i5.45iudssvcsasaciasetaaseeest dash svandasatea io cananthzestaasapeanaoasgestessanessaashosetaswetess +Documentation conventions +Include file epocdefs.inc + + +2 Segmented Memory Management ...............ccsscccsssssscsscsscssscsecssccsesssscscesssscssesssccscsssssssesssscssees DOL + + +Memory Segment naimes::i.ci:4cc.tistscssdaicesnigthosndshecetintiosnads ht eetdathesnnda beeetgatbosadaitiestdabas +Paras raps ns. cic; sh. chchcs cobs seeks dokcces Sees gua hacetcaes cous euch sdeewes cqunguske ocd ede Suvsgunbeces eoes Syuagunnecedetes boue +Permanent se@iments so: i.c508 Viste hab aihisien es Asians Aaehilen Sai ache +Directlyaccessin g: S6SiMeNts sai. et sakess aaches cessdieseeva deesecssduessscadeesecbideostetaceeedusadevssdyvedetaluneds +Size of available segmented MEMOTY ...........c ce eeseeeeseeesseecsseecesseeesseecsaeecscesseecesaeeesaeeesaeers +Creating a memory segment +Deleting a memory segment +Opening a memory segment % +ClosinS:a;memory Seement 5: .12:.3:5:45..1daisoeesacsvodendaiscsssactasseadaustestaacassendateaetaatassndaseasseaiay +Closing a locked or device SCQMENE........ eee eeseeeeseeeesneeesneecseecsseecesaeecsaeersaeeseneeeesaeeesaeers +Locking a MeMOFy SCYMENL........ eee eeeececeeseeceeeeseeececeeeeeeeseaeeecsesneeeceeeeeesseaeeeeeeseeeeeeaees +Unlocking a MeMOTY SCYMENL «ue eee eeeeceseeeeseeeseecseecseeceseecesaeecseaeessneeeetaeeeseeesaeers +Size‘of A MeEMOory SESMENE: s355:cisscsiszcssdalssesteseapesidsnscestegnapeahastsrestadsapeandgasoeedeass deusacenouetadase +Adjusting the size of a memory segment +Finding all s@ornents o.xisc3 4. oscek desedass doavices covudanscesvideatsazssveedata ds sadunacvas seach stbaaarete sade aobeaares +Copying to a MEMOTY SCYMENE ........ ee eeeeeeeeeceseeeeseeesseecseecscecsseecesaeessaeecseessseaeeesseeesaeers +Copying from a MEMOTY SEZMEN....... eee eeeeeseeesseeeeseeeceeecseeceseeeesaeecsaeessaeeseseeeesaeessaeers +Size OP RAM disk s:. cu ssisea shi neler ed adiaoki ded casi ne ole ciel + + +3 Heap Memory Management ...............ccccscccsscssscssscssecssscscecsscsscsssscssccssccsesssscssscsssscssessssssessssees OU + + +Dynamics:Of hedp mem Ory: i.5 ess.2¢ssco0s hes feist ss cog danheeevdsbestieatas, Hee easebalin fos chesdeystheed 3-1 +Allocating heap MEMOrys: .sc..iisBesstsaticestiahassitascessataocsidaatgesbeedateuensealeatieostosungeaseatheestans 3-1 +Re-allocating heap MeCMOTY.............seccesssecsssceesseeceseeeesseecsaeecseecsseesesseeesaeesseeseneeeeseeeenaes 3-2 +Adjusting the size of heap MeEMOTY................secesecceseceeseeeesscecesceceseeceseeeesacecssnecsseeseseeeeners 3-2 +Freeéms heap Memory x .2. 5:0. eck. codsdavssta davis coisteszdes Sbvke eedazeosdeu ubke fubadevsdon Stbbe peaduuaion aheaelo2es 3-3 +Size’of a:heap, cells: scssstsiavicisseslascsadaseassea lace aadacieastesiaocandacdeasteaaoeaniaisoasteaiaoeasacboesteayse 3-3 +Setting the heap: sranularity «nsec scadneciodtas ou nelendidshasio ied ost glibelsieveess 3-3 +Size.of available heap Memory 25:52:35.5 fos: ase sbereedash aaedesdeaediesnd assdiadeendasiansyiaonseeths 3-3 + + +4 Semaphore Management ..............cccssssccsscssscssccsecssccssscscesssscsessssccsccscscsssscsesssscsseessscssssscessess Ged + + +Creating a semaphores. :ci2issccanschasiehis itt eedatiosatdadcsaacstaneaneatieassboeadiodgdelesteoeaiguavenetas tees 4-1 +Deleting a semaphore.............cecccceeesscceessnceeceeeneeecesceeceeeneeeceseeeceseeeeeeseaeeeeeseeeseneaeeeseeanees 4-1 +Waiting on a Semaphore..........e.ccceseecccesssceeceeesseeeceeneeeeceeaeeeeseeeeecesnneeesseaeeeeeseaeeeeeenneeeeeeee 4-1 +Sie tall SON Ce ees’ ivis 505 seh eek Sees ects aes ted saves eed deve ee does eat Fee teasoeks dubs Sealed te Geese thy 4-2 +Signalling More than Once s....::ssctedsiesteaiateatlaeetesiscsatledsetensteetlidostasecentlaoeteaeiens 4-2 +Signalling once without re-schedule......... eee eeseesscecsseecsseecesseessaeecsaeecseecsseecesaeeesaeeesaeers 4-2 + + +March 1, 1999 + + +EPOC O/S SYSTEM SERVICES + + +5 Message Management ...............ccccccsssssssccsssccccsscceeccssssscsssceseccssscscecsseesccsssccsssessssssssscsssseeesssssees 5-1 +Inter process COMMUNICATION ............:ceeeeeeeceeeeneeeeeeeeceeeeeeeeeeeeneececeeenaeeeseeeeeeeseaeeeseenneeeeeeas 5-1 +Order of Message TECEPLION ice ciccciseeicveisetdccoigerdceeseenccevsdandeevedeaseesddaalesuedebdesuddesdeeidenisanecs 5-1 +The message system and the I/O system .............cessccceeeessceceesceeeeeeeeecesseeeeessneeceseaeeeeseaees 5-2 +Initializing the message SYSteM ............:cceeecseeessseceeeeeeeeeeeeeeeeeeeaeeeeeseaeeeeeenaeeeeseneeeeentaeeeees 5-2 +Asynchronous message reception ...........::ccceeecceeesseceeeeeeeeceseeeecensaeeeceseaeeeeeeaeeeeensaeeeeseanees 5-2 +Synchronous message reCeptiOn............csccceeeescccessseceeeeenceeeeeeeeeceenaeeecsseeeeeseeeecesteeeeeenees 5-3 +Cancelling queued message reCeive ...........cceeccceeeesceceeenececeeeneeeeseaeeeeeseaeeecseeeeesesaeeeeeenees 5-3 +Senin S MESSAGES... usdescesesesvetacsceuevas deveiuade ces scan cose dcanccvu cena dev deaacenvedaa Ooaucedascuccnaevandeneevandes 5-3 +Sending and getting a reply asynchromouslLy ..............:::cccesecceeeeesceeeeeeneeeceeeneeeessnneeeeeeeeeess 5-4 +Sending and waiting for a reply..........ececccceessccceceeeeeceeceenceceeseneeecesnneeecseeeeeeenaeeeeseneeeeeeeee 5-4 +FTGCii SA MeSSAGe aia ass ree aeons eeags Saves See Uelet ash Sail eae asOutess caved exe sbuutads Cousleseedlabeds cust eesescteseuals 5-4 +Requesting a signal from the SUpervisOL............:c::cccessseceeesenceeeeeeneeeeeeneeceeeeeeeeeseaeeeeeenees 5-5 +Cancelling requested signal from the Supervisor .............cccesecceeesenceeeeeseeeeeeeneeeeeenneeeeeeaeees 5-5 +Cancelling requested signal from the Supervisor by type ...........::::cceseesseceeeseeeeeeeteeeeeenees 5-6 + +6 Dynamic Library, Category and Object Management...............ccccsssccssssssccsscsecsssseessssceeeeees 6-1 +Pabrary Names 5 iss scaisesescatsseusta heels tas itatienatlalieentaaectlaieenitataelbatiec ts tecatis teats tates 6-1 +Loading a dymamic library............cecesccecessccceeesneeeeeseeeeecsenneeeeeeaeeeceenneeesesaeeeeeseneeeseenneeeeneas 6-1 +Unloading a dynamic library ...........ccccccceeeeccceessncceeeesaeeeeeseneeeceeeeeceseaeeeeessneeeessneeeeeeneeeess 6-2 +Banikanig 4 dyinarnie MaDrary cues sic: ese we cevs iuadevs ca vaces dana devs cana covtaiia tuvtalvecavhdin ofutteaeveest da ceaase 6-2 +Getting a dynamic library handle ............eeeccceceeecceeeeneceeesneeeeeeseeeeeeeneeeeeenneecessneeeeeneeeeess 6-2 +Getting a DYL handle by numbe’............... ce eeecccceseccceeeeneeeeeeeneeceeeneeeeeseaeeeeeseaeeessenneeeseees 6-3 +Creating an object by mUMber ............ceecccceeesccecesneeeceseneeeceeeeeecessaeeeeesnaeeeeeseeeeeneaeeeeeenees 6-3 +Creating an object by handle .0..........eeeecccceescccecssnececeesneeecesneecessaeeecessaeeecseneeeseseeeesenees 6-3 +Destroyii ean, ObjECte: iceitazssssusdasesstislacoutaadosetes aosendarsncatealaasntaaoesigasaeundasoeateniagcandateee? 6-4 +SemMGIMS a MESSAGE a5 5 coca se voctek Sesedes Sewsatehs gveanen cqusatetegenetancnonetenaunenen oeveemens dubecen puvedeensintett 6-4 +Sending a superclass MeSSAage...........ccseccccesseceeessnececeeeeeeceeneececseeeeeeseaeeeeesneeeceeseeaeeeeseanees 6-4 +Sending a direct MesSAGe ies vss ks se. seekeseese Na syen cubase ese based cuvtoyeceavasyun cova dyede cds Fyekdeveaneeces ieee 6-5 +EMiter: a; SNE MESSAGE ssicccsssvasevuecasceekegesdaanecaacousad sag ootadaadecassuagennaaesdenssdvapeatesuaGayssaueseaseecatads 6-5 +Open a multi library file... eee eeeeccceessceeceeneeeeeeeneeeceeneeeeesneeesseaeeeceeeaeeeensneeeeeneaeeeess 6-5 +Loading a multiple dynamic library..............ccceeecscceeescceeeeeneceeeceseneeeeeseeeeeseaeeecesnnseeeseanees 6-6 +Reclass an object by NUMDED ...............ceeeccceeesnceeeesneeeceeeneeecesneeeensaeeeessnaeeeesseeeeeneaeeeeneaaees 6-6 +Reéclass‘anobject by Wandle v2.3: vssscsiassudetowsteslassentavsneataaiarcutasaverigsincecandanseearagiateardarsee cd 6-7 +Copying data from a Cate QOry........escccceessccceeesnsceceeeeeeeeeseeeeeeeaeeeceseeeeeeeaeeeeseeaaaeeeseenneeeeeees 6-7 +Enter a:control Tést0ns, toes. dete hathiacdets a Bdeoiatdenaci edo deed titi lt 6-7 +Lea vitte a 'COntrol’ Te G1 OM )c225 esi ces Fees Beiet wes 08 hea 00aGa wes Syus Daete sec S aah ue (Seta eee 0a yen SeeS Ryka Ts danse 6-7 +Returning from a method. ...........ccccceeesscceeeseeeeeencecceeeaeeeceseceecesseeecsenaeeeessneeeeesseeeesenees 6-8 + +7 Device Managemen ............ccsscscccsscsssccsscssccssscscesssccscessscscesssscscssssssessssscsesssscssesssssesssssesesessees 7-1 +TIEVICETIAIMES 602. Aosed sets out te ooes oats arcutieds oobertiAdenetedeticne dea sciotedoteboveck eonttedecuavedscctetedomdssecoee 7-1 +TJOVICE=ATI VETS o35 osteo ebes eee ce eae ea oe aio ok oe An oo Sls ON ot ies 7-1 +Opening a physical device Ariver......... eee seesecceseecesceeseecseecseecsseesesaeeesaeessaeesseeesseeeesaes 7-1 +Getting the PDD entry point... ee eeeeeesecsseeeeseeeesseecsaeecsscecseecesaeeesaeecsaeecseeseseeeesaes 7-2 +Installing a device Ariver ...........ccceeceescceceesecceeesneeeceesneeeceeeeeceseaeeeeseeeeeeeeaeeeesseneeeesenneeeeeees 7-2 +Holding all device Arivers............ccceesscccceescceeeencecceeseeeecseeeceeseaeeecesneeeeeseeeeeeenneeeseenneeeeeeae 7-2 +Resuming all device Arivers.........e ee eeseesseecssceesseeceseeeesseecsseecscecsseecesseeesaeecsaeesseeseseeeenaes 7-3 +Loading a logical device Criver wi... eee ceeeeeesseeesneecssceceseecesaeecsaeecsacecseecsseeeesaeessaeessneeeeee 7-3 +Loading a physical device river .........e sc eeeceeeseeesneeceseecsseecesaeecsaeecsacecseecseeeeesaeessaeesseeeees 7-3 +Deleting: a device driver. c.csss. coseeigeiydik ogcestegisdesh be pheek eenadi gies Hesaylesbedenaghdesupbeseeeyeeideges 7-3 +Removing a device Ariver ............ccsscccceessceceeseceecesncecessaececessneecessaneeceseasesesuneesessaseeeseanees 7-4 +Querying the number Of Units ..0........ ce eeecccceeecccecesnececessneeeceseeeceneaeeeeeseaeeeeeseeeeeeeaeeeeseaees 7-4 +Finding all AG ViCesrs.3 2. ccccs cceseastc dovesntedsgotaue te sadetebesadaue dedaceh odes atseavevedes sdaselesscigentdgetesetlannises 7-4 +Callinga device vector ....s:taiiiet seiideieesteiebe dete piestdivdesdetepies dade debehi pda deseideeneaanegnls 7-5 + + +CONTENTS + + +8 Input Output Management ................ccccscccssssssccsscssecssscsecssscsseessscscecssssssssssscsesssscssesssscsssssscesoes 8-1 +Devices anid HES fics ccieiy sioee eis tegs te sitea tie seen Sete sdata iig step ody scenadee sauce dey sdehe eset tevsene a ested 8-1 +Sound ‘file format: states cain Peak pa la pin la ibaeiaobehed 8-1 +ASYNCHrONOUS T/O so seb os San Soes oh do beeak aie 0aY, DSc Dae se I eh Nl oes aoa aa ote ee eh Po oak 8-2 +Asynchronous I/O without error repOrting.........eeeeeeeseeeeseeseneeceseeeesaeecsneessaeessneeeesatessaeers 8-2 +SVNCHLONOUS: LO sees su. osasiedes oxdgstescvepedesbes pbanbeonpeds betes asubees bode Gedepbunteen dedessduprantersdedes sdevauesered 8-3 +Chainto root device ss..s:.cccsceinege sis abe nest edipaee antes ech paive died beeyaens oyeel begindenk epee easy 8-3 +Chain, to‘superclass devices. a.tiec 58 cithediteet ah aided at as oh steel eb i a ee ema 8-4 +Wait for I/O completion .0...... cee eeeeeeseecsscecsseeesseecesaeecsseecsseecseecsseecesaeeesaeessaeesseessneeeesaes 8-4 +Wait for specific request to Complete ........... eee eeseeesseeceseecesceeesseecsaeecseeceseeeesaeessaeessaeeeens 8-4 +Polling: for completion: .2..s:2 atee.i- Bytes hie agate belddoyiested bee depoeniann el egevienbeaadeiess 8-5 +Signalling Completion .................:::csesecsesessoreresseesonenecsonevessenensenensetenseesnonersonevenseneneetenseess 8-5 +Signalling completion by process ID ........eeseeesesescecsseeceseeeeseeeesseecsseesseeceeesesaesesaeessaeers 8-5 +Signalling completion with no reschedule ............escceeccessseeesneeceneeeeseeeeesaeecsaeecsseeeeseeeesaes 8-5 +Adding a handler: sic.e-ssc.g peeiteg.yotegigih teh voewncg geese vovead pees eye dagen Testo egapee eee ey 8-6 +Remiovin & a Wan letsy cx 22 sce ccictiec sek suit cesitest shat octastonk sitter tyst cas ul earache tant sees 8-6 +Enabling a handlets..2::s.vaiewli ncteientedi vinnie tau etal nas alaiewigsataucare. 8-6 +Requestie sa: Feset sess a cess Sil, tar feg ales Rueevet vey dations seat gales Sug eestadeyodeneeerewateddvede Suupvaxtees: 8-7 +Cancelling: a requested reset. .:.: s.vos.osa.pduet eisdelbegipaed Gade dedi plaid des esegapdaneedeyeldaeepiebenedees 8-7 +OPpeNiN Sa GEVICE: wocczten 2. eheak Toeet oes it eet oe ER eek oO a ae at ce a en Sak 8-7 +Closing a:dévices: sicistec hil ei navi ev a ee eee 8-8 +Reading from a CeVICC...... eee eeseeceseecesseecseecseecsseeeesaeecsaeecsseecsseecesaeecsaeesseessneeeesatessaeers 8-8 +Writing toa deVICE 2.205552 Gaye suesiytank epee aanvdonk Geipeekbeeap dees ath eaaedesd depeeldusaeoestdephibesnee eee 8-8 +SEEKING OF: a GEVICE so es hos She the et oho cata See abot cats Siet ok abcd ast tant cos heteroatoms Gestetvint sae? 8-8 +Mouse and keyboard 2:3 s.ve:.ates cava tales ee aith ian ceaieieieiiniausndgaaieicey 8-9 +Adding an application handler ........ eee eeeseecsseeceseeeesseecsscecsseecsseecesaeecsaeecsaeesseeesseeeesaes 8-9 +Removing an application handler ......... eee eeeeeseeesseeceseecsseecseeceseeeesaeeesaeecsaeesseeseseeeesaes 8-10 +Enabling an application handler... eee esceeeseecsseeeeeeeesseesseeceseecesaeeesaeecsaeessneeesseeessaes 8-10 +Getting theishift’states..:::..c4.c.css hs ties cel iin laren bk inn ainn linn nea 8-10 +Wait for I/O completion no handlers 20.0.0... eeeeeseeescecsseecesseeesseecscesaeecsseeesseeeesaeeesneeeaee 8-10 +Requesting a signal from the SUperViSOL...........:::ssccssecesseessseecsseecsseeceeeceseeessaeecsaeerseeenees 8-11 +Cancelling requested signal from the Supervisor ............c:ccessssceceeseecsneecsseessteecneeesseeeesaes 8-11 +Request signal on next half secondo... eeeeeeeseecseessneecseecseeceseeeesseesaeeesaeessaeeseneeeesaeen 8-11 +Query the completion of IoNextHalfSecond ....... cee eeeeeseecsseeceseeeeseecsaeecseesaeessseeesseeeesaes 8-12 +Playing back a sound file synChromousSly.............essesessseeeeseecsscecsseecneeceseeeesaeecsaeecseesnnees 8-12 +Playing back a sound file asynChronousSly............esecseseceseecsseeesseeeesaeecseesneecsaeecseeeeseeeesaes 8-12 +Cancelling playing back a sound file oo... eee eeeseeceecesseecseecsceceseeeeseeeseeeesaeecsaeesseeesnees 8-13 +Recording sound to file synchronously ............cceseceseseeesseeeescessseeseecscecesaeeesaeecsaeesaeeesaeers 8-13 +Recording sound to file asynChronously............cceecesssecesseessseecssceceseesseeceseeeesaeecsaeesseeeaeers 8-14 +Cancelling recording sound to a file... eee eeeeesceseessseecseecsceceseeceeeceseeeesaeecsaeesseeesnees 8-14 +Input Output Management update 0.0... eee eeeeeseeceeneeceeecsscecsseeeesaeecsaeesseecssaeeesaeessaeers 8-15 + +Asynchronous partial sound file replay .........ceeeeeceeeseeceneessseeceeeeeesseecsseecsaeeseseeeesaes 8-15 + +D File: Manageme nt sccccicecsescicecstccssecsasseosssessasesbaséosesencsosusenssocvsaddsoeebsedsonsbeddsondnsassseeensesoavonssseases 9-1 +TRE ALE: SOR VEL, sas s2ich coset iss 522s Seve ta bos cck Fibs feist basen Big Pete Ses ovd Rana voevd ba Aes cvd Saeanetes 9-1 +Connecting to the file‘serverssissieacstdss.cs.istsceatdsascastisioeatasssass testes atabasoeeleateaeataiaaselas eens 9-1 +Execute-an amie tiles cscs aul sie Gulia ie A Be eels 9-1 +Parse-a-file name is: ssthess deste Asvtitehivtins Anoisbe Ash. ns Aaphesichepions Aativascup cassislaamiers Aneaisins 9-2 +Get Current Path ss sss. cers sieccck siunecudtauis seb saues cvssecbs dub sevbs rodbarie feb sanyesevechvededsteeesesetevesvescevesvecdes 9-2 +Set current: Paths icecs.ssguscscadesesesscesssesseaseoohesascesseaisesbesasseredsassostesendsoddsavevets desssetdsassoata suey 9-3 +Test Path: available si: 265. scchSsegesue ces seehs dckewus cess ceebosehesus Sesetues dele sea ravbevelosesevtacisl Seresbeveasaeh od 9-3 +Deléting:a filer ditectOry...si.:sis,oah sinew alain oun danse ek Baaie A 9-3 +Renaming a file:or directory. sic csss2h oxsevs thus Pesach ws eoes ch sstadeuseusacieosdubeeets buastbethessshackencudstanedy 9-4 +Getting file or directory, Status: :i.:sic:.ce.iishspeciesi.cestestageatasisceteaiapeasensoesles at easaceionelaseseees 9-4 +Setting file or GirectOry Status................:csesesseresesereneeteneeecsonerssevensetenseessonertsevensetenseees 9-4 +Getting: device status. ic. s. levis syiekeseedastvsvdasiseedsaesbeascssadisesvaghuse ovsidessdvasdes usibereserdios se 9-5 +Gettinig’ file System Status... :r03>= 1E+100. +UnderflowErr Float << 1E-99. + + +PANIC: None + + +Converts a double floating point number in [SI] to a printable ASCII zero terminated string pointed to by +DI using the supplied format specification. The format specification is contained in the ptobEnt structure +as defined in epocdefs.inc as: + + +Dtob struc ; dtob format string structure +DtobType db ? j conversion type +DtobWidth db +DtobNdec db +DtobPoint db +DtobTriad db +DtobTrilen db ; threshold for triad character use +DtobEnt ends + + +; width of representation in characters +; number of decimal places + +; decimal point character + +; triad separator character + + +VN VV Vy + + +Numbers may be represented in various formats by setting ptobType as follows:- +@ DtobTypeFixed, fixed point format. +@ DtobTypeExponent, exponent format. +@ DtobTypeGeneral, general format. + + +Integer format is obtained as a special case of fixed point format where the number of decimal places +required is zero. The parameter [DX].pt obwidth specifies the maximum number of characters allowed to +represent the number and there should be [DX].pt obwidth+1 bytes (the +1 is for the zero terminator) +reserved at DI. If the output exceeds this limit, railzrr is returned. Although numbers are normally +displayed right-aligned, convFloat ToBuffer makes no attempt to align the result in the buffer. Alignment +is quite different for monospaced and proportionally spaced character fonts and is best handled by post- +processing the output from convFloatToBuffer. + + +[DX].pt obwidth should be in the range | to 255 inclusive. The parameter [DX].ptobNdec specifies the +number of decimal digits following the decimal point when [DX].pDtobType 1S DtobTypeFixed OF +DtobTypeExponent. [DX].ptobNdec must be in the range 0 to FloatSignificantDigits (15 for IEEE +floating point format) inclusive. The parameter [DX].ptobPoint specifies the decimal point character +which separates the integer portion from the fractional portion and would normally be either a'.' or a',’ . + + +The parameter [DX].pt obTriad specifies the triad separator character which delimits groups of 3 digits in +the integer part of the fixed point representation and would normally be either ',’ or '.' or '' . The +insertion of triad separation characters is disabled if [DX].ptobTrilen is 0 and otherwise enabled when +the integer portion of the number contains greater than [DX].ptobTrilen digits. Normally one would use +[DX].ptobTrilen=1 to enable triad separation and [DX].ptobTrilen is 4 to conform to French + + +conventions for triad separator insertion. + + +In all cases, negative numbers are represented by the insertion of a leading '-' sign (positive numbers do +not have a leading '+' sign). This can easily be post-processed to obtain a bracketed representation of +negative numbers, if desired. There can never be more than FloatSignificantDigits(15 FOR IEEE +floating point format). Where there are less than FloatSignificantDigits, the number is rounded to the +number of significant digits displayed. + + +12-4 + + +12 CONVERSION MANAGEMENT + + +The limitation to floats with magnitude between 1E-99 and 1E+100 results from the use of lookup tables +for speedily generating the results. Floating point numbers of magnitude smaller than 1E-99 can easily be +converted to 0 before calling this service. The detailed formatting details as a function of [DX].ptobtType +is as follows: + + +@ DtobTypeFixed - The number is represented with [DX].pt obNdec decimal places where +[DX].pt obNdec may be zero to represent an integer (in which case no decimal point character is +displayed). If the ASCII form exceeds [DX].pt opbwidth (usually due to the number being large +and having too many digits before the decimal point), railzrr is returned. A zero is displayed in +the form "0.000" where there are [DX].pt obNdec zeros following the decimal point or as just "0" +if [DX].DtobNdec is zero. + + +@ DtobTypeExponent - The number is represented in exponent notation with one non-zero digit +before the decimal point and [DX].pt obNdec digits beyond the decimal point followed by 'E', a +sign ('+' or '-') and the exponent as two digits (with leading zero if necessary). If [DX].ptobNdec +is zero, the number is rounded to one digit of precision and no decimal point is displayed. A zero +is displayed in the form "0.000E+00" where there are [DX].pt obNdec zeros following the decimal +point or as "OE+00" if [DX].ptobNdec is zero. Triad separation is not available and triad +separation parameters are ignored. + + +@ DtobTypeGeneral - converts either as fixed format (with no triad separator) or exponent format, +making best use of [DX].ptobwidth. Here, "making best use" is defined as showing the greater +number of significant digits and preferring fixed format when the number of significant digits +shown is the same. The number of decimal places is chosen as a function of [DX].ptobwidth and +the value of [DX].pt obNdec is ignored. A zero is displayed as just "0". Triad separation is not +available and triad separation parameters are ignored. + + +ConvStringToFloat String to float + + +SI address of pointer to text to convert +Dx Decimal point character +DI Pointer to double destination + + +RETURN: Carry clear + + +Success +RETURN: = Carry set +FailErr Failed to recognise a number. +OverflowErr Number too large. +UnderflowErr Number less than 1E-99, 0 written to [DI]. + + +PANIC: None + + +Scans the string for a number and writes the value as a double float to [DI]. If underflow occurs, zero is +written to [DI]. + + +The supplied ASCTI string should take the form: +[+|-]<.[E|e] [+|-]<> +Where: + + +e = The leading '+' sign may be omitted for positive numbers. <> and <> are optional +but at least one should be present. + + +e Leading zeros in are legal but have no effect. +e = Trailing zeros in are legal but have no effect. + + +e = There is no reasonable limit to the number of significant digits but digits which are beyond the +precision of the floating point representation will not be reflected in the mantissa of the number +which is produced. + + +e The exponent field which starts with and 'E' or 'e' is optional. +e = The leading '+' sign in the exponent field may be omitted for positive exponents. + + +e The resulting number should be in the range approximately 1e-99 to approximately 1e+99. + + +12-5 + + +CHAPTER 13 + + +LONG INTEGER MANAGEMENT + + +e LongintCompare Compare two long integers +AX: BX The left operand long integer. +CX:DX The right operand long integer. +RETURN: +Flags < 0 If AX:BX < CX:DX +Flags = 0 If AX:BX = CX:DX +Flags >> 0 If AX:BX > CX:DX + + +PANIC: None + + +Compares two long integers for equality. The flags are set in the same way as for a normal compare for +integers, i.e. CMP AX:BX, CX:DX. + + +Note that the flags are set so that only the signed tests can be performed, i.e. JLE,JL,JE,JNE,JG,JGE and +not the unsigned tests JB,JBE,JA,JAE. + + +All registers are preserved by this service. + + +e LongintMultiply Long integer multiplication +AX:BX The left operand long integer. +CX:DX The right operand long integer. +RETURN: = Carry clear +AX:BX Product. +RETURN: Carry set +OverflowErr AX:BX * CX:DX is bigger than 32 bits. + + +PANIC: None + + +Multiply two long integers together. If the resultant product overflows then an error will be returned by +setting the carry flag. + + +If no error occurs, the flags will not be set for the result; carry will be clear. + + +e LongintDivide Long integer division +AX: BX The left operand long integer (dividend). +CX:DX The right operand long integer (divisor). +RETURN: = Carry clear +AX: BX The quotient. +CX:DX The remainder. +RETURN: Carry set +DivideByZeroErr CX:DX is zero. + + +PANIC: None + + +13-1 + + +EPOC O/S SYSTEM SERVICES + + +Divide one long integer by another. +If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. +If no error occurs, the flags will not be set for the result; carry will be clear. + + +The remainder will have the same sign as the dividend. + + +e LongUnsignedintCompare Compare 2 unsigned long integers + + +AX:BX The left operand unsigned long integer. + +CX:DX The right operand unsigned long integer. +RETURN: + +Flags << 0 If AX:BX < CX:DX + +Flags = 0 If AX:BX = CX:DX + +Flags > 0 If AX:BX > CX:DX + + +PANIC: None + + +Compares two unsigned long integers for equality. +The flags are set in the same way as for a normal compare for integers, i.e. CMP AX:BX, CX:DX. + + +Note that the flags are set so that only the unsigned tests can be performed, i.e. JBE,JB,JE,JNE,JA,JAE +and not the signed tests JL,JLE,JG,JGE. + + +All registers are preserved by this service. + + +e LongUnsignedintMultiply Unsigned long integer multiplication + + +AX:BX The left operand unsigned long integer. +CX:DX The right operand unsigned long integer. +RETURN: Carry clear +AX:BX Product. +RETURN: Carry set +OverflowErr AX:BX * CX:DX is bigger than 32 bits. + + +PANIC: None +Multiply two unsigned long integers together. + + +If the resultant product overflows, an error will be returned by setting the carry flag. + + +If no error occurs, the flags will not be set for the result; carry will be clear. + + +e LongUnsignedIntDivide Unsigned long integer division +AX:BX The left operand unsigned long integer (dividend). +CX:DX The right operand unsigned long integer (divisor). +RETURN: Carry clear +AX: BX The quotient. +CX:DX The remainder. +RETURN: Carry set +DivideByZeroErr CX:DX is zero. + + +PANIC: None + + +Divide one unsigned long integer by another. +If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. + + +If no error occurs, the flags will not be set for the result; carry will be clear. + + +13-2 + + +13 LONG INTEGER MANAGEMENT + + +LongUnsignedintRandom Unsigned long integer random number + + +DS:BX Pointer to the unsigned long integer seed. +RETURN: +AX: BX The unsigned long integer random number. + + +PANIC: None +Return an unsigned long integer random number given the seed. +The 4 bytes pointed to by BX are used to generate the next random number which is returned in AX:BX + + +as well as being written back to the seed. The seed can start with any number required from which the +same sequence of random numbers will be generated. + + +CHAPTER 14 + + +FLOATING POINT NUMBER HANDLING + + +e FloatCompare Compare two Floats +DI Pointer to left hand floating point operand. +SI Pointer to right hand floating point operand. +RETURN: +Z flag set if [DIJ=[S]]. +S flag set if [DI]<<[S]]. + + +PANIC: None + + +Compares the two floating point operands pointed to by SI and DI, setting the Z and the S flags as for +[DI]-[SI]. The Z flag is set if the operands are equal and the S flag is set if [DI] is less than [SI]. + + +¢ FloatMultiply Multiply two floats +DI Pointer to left hand (and destination) floating point operand. +Si Pointer to right hand floating point operand. +RETURN: = Carry clear +[DI] +RETURN: Carry set +OverFlowError Product exponent overflowed. + + +PANIC: None +Multiplies the two floating point operands pointed to by SI and DI. Returns the product in [DI]. + + +« FloatDivide Divide floats +DI Pointer to left hand (and destination) floating point operand. +SI Pointer to right hand floating point operand. +RETURN: = Carry clear +[DI] +RETURN: Carry set +OverFlowError Quotient exponent overflowed. + + +PANIC: None +Divides the operand at DI by the operand at SI and returns the quotient in [DI]. + + +14-1 + + +EPOC O/S SYSTEM SERVICES + + +e FloatAdd Add two Floats + + +DI Pointer to left hand (and destination) floating point operand. +SI Pointer to right hand floating point operand. +RETURN: Carry clear +[DI] +RETURN: Carry set +OverFlowError Sum exponent overflowed. + + +PANIC: None +Adds the two floating point operands pointed to by SI and DI. Returns the sum in [DI]. + + +¢ FloatSubtract Subtract Floats +DI Pointer to left hand (and destination) floating point operand. +SI Pointer to right hand floating point operand. +RETURN: Carry clear +[DI] +RETURN: = Carry set +OverFlowError Sum exponent overflowed. + + +PANIC: None +Subtracts the operand at SI from the operand at DI and returns the difference in [DI]. + + +e FloatNegate Negate a Floats + + +DI Pointer to floating point operand. +RETURN: + +[DI] +PANIC: None +Negates the float at DI. + + +¢ FloatToLong Convert Float to a signed long +SI Pointer to float operand to be converted. + +RETURN: Carry clear +AX:BX Long integer result. + +RETURN: Carry set +ArgumentErr Float not in range [-2**31,2**31-1]. + + +PANIC: None + + +Converts the floating point operand pointed to by SI to a 32 bit signed long integer in AX:BX with the +most significant word in AX. + + +¢ FloatTtoUnsignedLong Convert Float to unsigned long +SI Pointer to float operand to be converted. + +RETURN: Carry clear +AX: BX Unsigned long integer result. + +RETURN: Carry set +ArgumentErr Float not in range [-2*32+1,2**32-1]. + + +PANIC: None + + +Converts the floating point operand pointed to by SI to a 32 bit unsigned integer in AX:BX with the most +significant word in AX. Note that the sign of the float is ignored. + + +14-2 + + +14. FLOATING POINT NUMBER HANDLING + + +¢ FloatTolnt Convert Float to a signed integer +SI Pointer to float operand to be converted. + +RETURN: Carry clear +AX unsigned integer result. + +RETURN: Carry set +ArgumentErr Float not in range [-32768,32767]. + + +PANIC: None +Converts the floating point operand pointed to by SI to a 16 bit signed integer in AX. + + +¢ FloatToUnsignedint Convert Float to unsigned integer +SI Pointer to float operand to be converted. + +RETURN: Carry clear +AX Integer result. + +RETURN: Carry set +ArgumentErr Float not in range [-65535,65535] + + +PANIC: None + + +Converts the floating point operand pointed to by SI to a 16 bit unsigned integer in AX. The sign of the +float is ignored. + + +¢ LongToFloat Convert signed long to Float +AX:BX Signed long to be converted. +DI Pointer to destination float. + +RETURN: +[DI] + + +PANIC: None +Converts the signed 32 bit integer in AX:BX to a float at DI. + + +¢ IntToFloat Convert signed integer to Float +AX Signed integer to be converted. +DI Pointer to destination float. + +RETURN: +[DI] + + +PANIC: None +Converts the signed 16 bit integer in AX to a float at DI. + + +¢ UnsignedIintToFloat Convert unsigned integer to Float +AX Unsigned integer to be converted. +DI Pointer to destination float. + +RETURN: +[DI] + + +PANIC: None +Converts the unsigned 16 bit integer in AX to a float at DI. + + +CHAPTER 15 + + +FLOATING POINT FUNCTION INTERFACE + + +FloatASin Arcsine of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float. + + +PANIC: None + + +Calculates the Arcsine in radians of a double argument in [SI] returning the result in [DI]. [SI] is +preserved unless SI equals DI. + + +FloatATan Arctangent of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: = Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float. + + +PANIC: None + + +Calculates the Arctangent in radians of a double argument in [SI] returning the result in [DI]. [SI] is +preserved unless SI equals DI. + + +FloatCos Cosine of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: = Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float, or argument not in range. + + +PANIC: None + + +Calculates the Cosine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved +unless SI equals DI. + + +15-1 + + +EPOC O/S SYSTEM SERVICES + + +FloatExp Exponentiation of a float + + +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float. +PANIC: None + + +Calculates the exponentiation of a double argument in [SI] returning the result in [DI]. [SI] is preserved +unless SI equals DI. + + +Floatint Zero fractional part of a Float + + +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float. +PANIC: None + + +Removes the fractional part of the float in [SI] and returns the result as a float in [DI]. [SI] is preserved +unless SI equals DI. + + +FloatLn Natural logarithm of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float, or argument not greater than zero. + + +PANIC: None + + +Calculates the Natural Logarithm of a double argument in [SI] returning the result in [DI]. [ST] is +preserved unless SI equals DI. + + +FloatLog Logarithm of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float, or argument not greater than zero. + + +PANIC: None + + +Calculates the Logarithm of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless +ST equals DI. + + +15 -2 + + +15 FLOATING POINT FUNCTION INTERFACE + + +FloatMod Modulo of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +Dx Pointer to floating point modulo value. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float. +OverflowErr Integer overflow. + + +PANIC: None + + +Calculates [SI] modulo [DX] returning the result in [DI]. The calculation is [DI] = [ST] - +FloatInt({[S1]/[DX])*[DX]. [SI] and [DX] is preserved unless SI or DX equals DI. + + +FloatPow Power of two Floats +DI Pointer to destination floating point operand. +SI Pointer to floating point base. +Dx Pointer to floating point power. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float, 040, or [SI]<<0O with [DI] not integral. +OverflowErr Integer overflow. + + +PANIC: None + + +Calculates [SI] raised to the power of [DI] returning the result in [DI]. [SI] and [DX] are preserved unless +SI or DI equals DI. + + +FloatRand Float random number + + +DI Pointer to destination floating point number. +SI Pointer to unsigned long integer seed. +RETURN: Carry clear +[DI] +RETURN: Carry Set +None +PANIC: None + + +Generates a pseudo random number using the unsigned long integer seed in [SI] and returns the result in +[DI]. [SI] is preserved unless SI equals DI. + + +FloatSin Sine of a Float + + +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: +RETURN: Carry clear + +[DI] +RETURN: Carry Set + +ArgumentErr Invalid float, or argument not in range. +PANIC: None + + +Calculates the Sine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved +unless SI equals DI. + + +15-3 + + +EPOC O/S SYSTEM SERVICES + + +FloatSqrt Square root of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +ArgumentErr Invalid float or argument less than 0. + + +PANIC: None + + +Calculates the square root of a double argument in [SI] returning the result in [DI]. [SI] is preserved +unless SI equals DI. + + +FloatTangent Tangent of a float +DI Pointer to destination floating point operand. +SI Pointer to floating point function argument. +RETURN: Carry clear +[DI] +RETURN: Carry Set +OverflowErr Input argument equals PI/2. + + +PANIC: None + + +Calculates the Tangent in radians of a double argument in [SI] returning the result in [DI]. [ST] is +preserved unless SI equals DI. + + +15-4 + + +CHAPTER 16 + + +CHARACTER MANAGEMENT + + +¢ CharlsDigit Character is a digit + + +AL The character to be tested. +RETURN: + +Z flag = 0 If character is a digit. + +Z flag = 1 If character is not a digit. + + +PANIC: None + + +Returns the flags set depending on whether the character in AL is a digit. This is a language dependent +service. + + +e CharlsHexDigit Character is a hexadecimal digit +AL The character to be tested. + +RETURN: +Z flag = 0 If character is a hexadecimal digit. +Z flag = 1 If character is not a hexadecimal digit. + + +PANIC: None + + +Returns the flags set depending on whether the character in AL is a hexadecimal digit. This is a language +dependent service. + + +¢ CharlsPrintable Character is printable +AL The character to be tested. + +RETURN: +Z flag = 0 If character is printable. +Z flag = 1 If character is not printable. + + +PANIC: None + + +Returns the flags set depending on whether the character in AL is printable. This is a language dependent +service. + + +¢ CharlsAlphabetic Character is alphabetic +AL The character to be tested. + +RETURN: +Z flag = 0 If character is alphabetic. +Z flag = 1 If character is not alphabetic. + + +PANIC: None + + +Returns the flags set depending on whether the character in AL is alphabetic. This is a language +dependent service. + + +16-1 + + +EPOC O/S SYSTEM SERVICES + + +¢ CharlsAlphaNumeric + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +Character is alphabetic or digit + + +The character to be tested. + + +If character is alphanumeric. + + +If character is not alphanumeric. + + +Returns the flags set depending on whether the character in AL is alphanumeric. This is a language + + +dependent service. + + +« CharlsUpperCase + + +AL +RETURN: +Z flag = 0 +Z flag =1 +PANIC: None + + +Character is upper case + + +The character to be tested. + + +If character is upper case. + + +If character is not upper case. + + +Returns the flags set depending on whether the character in AL is upper case. This is a language + + +dependent service. + + +e CharlsLowerCase + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +Character is lower case + + +The character to be tested. + + +If character is lower case. + + +If character is not lower case. + + +Returns the flags set depending on whether the character in AL is lower case. This is a language + + +dependent service. + + +« CharlsSpace + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +Character is space + + +The character to be tested. + + +If character is space. + + +If character is not space. + + +Returns the flags set depending on whether the character in AL is a space. This is a language dependent + + +service. + + +e CharlsPunctuation + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +Character is punctuation + + +The character to be tested. + + +If character is punctuation. + + +If character is not punctuation. + + +Returns the flags set depending on whether the character in AL is punctuation. This is a language + + +dependent service. + + +16-2 + + +e CharlsGraphic + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +16 CHARACTER MANAGEMENT + + +Character is graphic + + +The character to be tested. + + +If character is graphic. + + +If character is not graphic. + + +Returns the flags set depending on whether the character in AL is graphic. This is a language dependent + + +service. + + +e CharlsControl + + +AL +RETURN: +Z flag = 0 +Z flag = 1 +PANIC: None + + +Character is control + + +The character to be tested. + + +If character is control. + + +If character is not control. + + +Returns the flags set depending on whether the character in AL is control. This is a language dependent + + +service. + + +¢ CharToUpperChar + + +AL +AH + +RETURN: +AL +AH + + +PANIC: None + + +Characters to upper case + + +A character to be converted. + + +A character to be converted. + + +Converted to upper case. + + +Converted to upper case. + + +Converts the characters in AH and AL to upper case. This is a language dependent service. + + +e CharToLowerChar + + +AL +AH + +RETURN: +AL +AH + + +PANIC: None + + +Characters to lower case + + +A character to be converted. + + +A character to be converted. + + +Converted to lower case. + + +Converted to lower case. + + +Converts the characters in AH and AL to lower case. This is a language dependent service. + + +e CharToFoldedChar + + +AL +AH + +RETURN: +AL +AH + + +PANIC: None + + +Characters to folded characters + + +A character to be folded. +A character to be folded. + + +Folded. +Folded. + + +Folds the characters in AH and AL. This is a language dependent service. + + +CHAPTER 17 + + +BUFFER MANAGEMENT + + +¢ BufferCopy Copy one buffer to another +DS:SI Pointer to source buffer. +ES:DI Pointer to target buffer. +CX Number of bytes to copy. + + +RETURN: None + +PANIC: None + +Copies CX bytes of data from the source buffer to the target buffer. + +The service is optimised to perform the copy in words. If the target buffer pointer is greater than the + + +source buffer pointer, the copy will be done backwards so as to avoid the possibility of corrupting the +source buffer during the copy. In most cases it is better to use the REP MOVSW 80C86 instruction. + + +¢ BufferSwap Swap the contents of two buffers +DS:SI Pointer to one of the buffers. +ES:DI Pointer to the other buffer. +CX The number of bytes to swap. + + +RETURN: None +PANIC: None + + +Swap the contents of the two buffers pointed to by SI and DI. CX bytes of data will be swapped. This +service is optimised to use words. + + +¢ BufferCompare Compare one buffer with another +DS:SI Pointer to left operand buffer. +ES:DI Pointer to right operand buffer. +CX Number of bytes in the left operand. +BX Number of bytes in the right operand. +RETURN: +Flags < 0 If [SY] < [DI] +Flags = 0 If [SI] = [DI] +Flags > 0 If [SY] > [DI] + + +PANIC: None + + +Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, +i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed +comparisons such as JAE etc. will lead to unpredictable results. This service makes the comparison +dependent on the case. + + +17-1 + + +EPOC O/S SYSTEM SERVICES + + +« BufferCompareFolded Compare a buffer with another folded +DS:SI Pointer to left operand buffer. +ES:DI Pointer to right operand buffer. +cx Number of bytes in the left operand. +BX Number of bytes in the right operand. +RETURN: +Flags < 0 If [SI] < [DI] +Flags = 0 If [SI] = [DI] +Flags > 0 If [SI] > [DI] + + +PANIC: None + + +Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, +i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed +comparisons such as JAE etc. will lead to unpredictable results. + + +This service is case independent and is language dependent. + + +« BufferLocate Locate a character in a buffer +AH The character to be located. +DS:SI Pointer to the buffer to be searched. +cx The number of bytes in the buffer to be searched. +RETURN: Carry clear +AX Index of the character in the string. +RETURN: Carry set +AL undefined Character is not in the string. + + +PANIC: None + + +Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the +character is located then the index into the buffer is returned in AX. The index of the first character in the +buffer is 0. + + +This service is case dependent. + + +« BufferLocateFolded Locate a character in a buffer folded +AH The character to be located. +DS:SI Pointer to the buffer to be searched. +CX The number of bytes in the buffer to be searched. +RETURN: Carry clear +AX Index of the character in the string. +RETURN: Carry set +AL undefined Character is not in the string. + + +PANIC: None + + +Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the +character is located then the index into the buffer is returned in AX. The index of the first character in the +buffer is 0. + + +This service is case independent. + + +17-2 + + +e BufferSubBuffer + + +DS:SI +ES:DI +cx +BX + +RETURN: Carry clear +AX + +RETURN: Carry set +AL undefined + + +PANIC: None + + +17 BUFFER MANAGEMENT + + +Find a sub-buffer in a buffer + + +Pointer to the buffer to be searched. + +Pointer to the buffer to be located. + +The number of bytes in buffer being searched. +The number of bytes in sub-buffer. + + +Offset of the sub-buffer within the buffer. + + +Sub-buffer not found. + + +Locates a buffer as a sub-buffer within another buffer. + + +If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length +CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to +by SI and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a +sub-buffer, then the service returns the carry flag set. + + +This service is case dependent. + + +- BufferSubBufferFolded Find a sub-buffer in a buffer folded + + +DS:SI Pointer to the buffer to be searched. + +ES:DI Pointer to the buffer to be located. + +cx The number of bytes in buffer being searched. + +BX The number of bytes in sub-buffer. +RETURN: Carry clear + +AX Offset of the sub-buffer in the buffer. + + +RETURN: Carry set +AL undefined. +PANIC: None + + +Locates a buffer as a sub-buffer within another buffer. + + +Sub-buffer not found. + + +If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length +CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to +by SI, and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a +sub-buffer, then the service returns the carry flag set. + + +This service is case independent. + + +- BufferMatch Match a wild card buffer + + +DS:SI Pointer to the buffer to be searched. + +CX Length of the buffer to be searched. + +ES:DI Pointer to the wild card match buffer. + +Dx Length of the match buffer. +RETURN: Carry clear + +Match + + +RETURN: = Carry set +AL undefined + +PANIC: None + +Search a buffer for a match with the supplied wild card buffer. + + +No match. + + +17 -3 + + +EPOC O/S SYSTEM SERVICES + + +If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does +not match then the service will return with carry set. The matchany character will match any set of +characters. The MatchSingle character will match any single character. + + +This service is case dependent. + + +- BufferMatchFolded Match a wild card buffer folded + + +DS:SI Pointer to the buffer to be searched. +cx Length of the buffer to be searched. +ES:DI Pointer to the wild card match buffer. +Dx Length of the match buffer. +RETURN: Carry clear +Match +RETURN: = Carry set +AL undefined No match. + + +PANIC: None +Search a buffer for a match with the supplied wild card buffer. + + +If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does +not match then the service will return with carry set. The Matchany character will match any set of +characters. The MatchSingle character will match any single character. + + +This service is case independent. + + +- BufferJustify Justify a buffer + + +DS:SI Pointer to the buffer to be justified. +Cx Length of the buffer to be justified. +ES:DI Pointer to the target buffer. +BX Length of the target buffer. +DL JustifyLeft OF JustifyCentre Of JustifyRight. +DH The fill character. +RETURN: +AX Points to the character after the last byte copied to the target buffer. + + +PANIC: None + + +Justifies a source buffer DS:SI of length CX into a target buffer ES:DI of length BX using the justification +method passed in DL and the fill character passed in DH. If BX is negative, then BX bytes are just copied +to the target buffer. If DL is not one of the 3 options then the left justified method will be used by default. + + +17-4 + + +CHAPTER 18 + + +STRING MANAGEMENT + + +¢ StringCopy Copy one string to another +DS:SI Pointer to source string. +ES:DI Pointer to target string. + + +RETURN: None +PANIC: None +Copies the source string to the target string. + + +¢ StringCopyFolded Copy one string to another folded +DS:SI Pointer to source string. +ES:DI Pointer to target string. + + +RETURN: None +PANIC: None +Copies the source string to the target string. Characters are folded as they are copied. + + +¢ StringConvertToFolded Convert a string to folded + + +DS:SI Pointer to string to be folded. +RETURN: None +PANIC: None +Converts the string pointed to by SI to folded. + + +¢ StringCapitalise Capitalise a string + + +DS:SI Pointer to string to be capitalised. +RETURN: None +PANIC: None + + +Converts the string pointed to by SI so that the first letter is uppercase and the remaining characters are +lowercase. + + +e StringCompare Compare one string with another +DS:SI Pointer to left operand string. +ES:DI Pointer to right operand string. +RETURN: +Flags < 0 If [SY] < [DI] +Flags = 0 If [SI] = [DI] +Flags > 0 If [ST] > [DI] + + +PANIC: None +Compares two strings for equality. + + +18-1 + + +EPOC O/S SYSTEM SERVICES + + +The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets +the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will +lead to unpredictable results. + + +This service is case dependent. + + +¢ StringCompareFolded Compare a string with another folded +DS:SI Pointer to left operand string. +ES:DI Pointer to right operand string. +RETURN: +Flags < 0 If [SI] < [DI] +Flags = 0 If [ST] = [DI] +Flags > 0 If [ST] > [DI] + + +PANIC: None + + +Compares two strings for equality. + + +The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets +the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will +lead to unpredictable results. + + +This service is case independent and language dependent. + + +¢ StringMatch Match a wild card string + + +DS:SI Pointer to the string to be searched. +ES:DI Pointer to the wild card match string. +RETURN: Carry clear +Match +RETURN: = Carry set +AL undefined No match. +PANIC: None +Search a string for a match with the supplied wild card string. +If the wild card string matches then the service will return with carry clear. If the wild card string does not + + +match then the service will return with carry set. The mat chany character will match any set of characters. +The matchSingle character will match any single character. + + +This service is case dependent. + + +¢ StringMatchFolded Match a wild card string folded + + +DS:SI Pointer to the string to be searched. +ES:DI Pointer to the wild card match string. +RETURN: Carry clear +Match +RETURN: = Carry set +AL undefined. No match. + + +PANIC: None + + +Search a string for a match with the supplied wild card string. + + +If the wild card string matches then the service will return with carry clear. If the wild card string does not +match then the service will return with carry set. The mat chany character will match any set of characters. +The matchsingle character will match any single character. + + +This service is case independent. + + +18 -2 + + +18 STRING MANAGEMENT + + +« StringLocate Locate a character in a string +AH The character to be located. +DS:SI Pointer to the string to be searched. +RETURN: Carry clear +AX Index of the character in the string. +RETURN: Carry set +AL undefined Character is not in the string. + + +PANIC: None +Locates the character in AH within the string pointed to by SI. + + +If the character is located then the index into the string is returned in AX. The index of the first character +in the string is 0. + + +This service is case dependent. + + +¢ StringLocateFolded Locate a character in a string folded +AH The character to be located. +DS:SI Pointer to the string to be searched. +RETURN: Carry clear +AX Index of the character in the string. +RETURN: Carry set +AL undefined Character is not in the string. + + +PANIC: None +Locates the character in AH within the string pointed to by SI. + + +If the character is located then the index into the string is returned in AX. The index of the first character +in the string is 0. + + +This service is case independent. + + +¢ StringLocatelnReverse Locate a character in reverse +AH The character to be located. +DS:SI Pointer to the string to be searched. +RETURN: Carry clear +AX Index of the character in the string. +RETURN: Carry set +AL undefined Character is not in the string. + + +PANIC: None + + +Locates the character in AH within the string pointed to by SI in reverse order. + + +If the character is located then the index into the string is returned in AX. The index of the first character +in the string is 0. + + +This service is case dependent. + + +¢ StringLocatelnReverseFolded Locate char’ in reverse folded +AH The character to be located. +DS:SI Pointer to the string to be searched. + +RETURN: Carry clear +AX Index of the character in the string. + + +EPOC O/S SYSTEM SERVICES + + +RETURN: Carry set +AL undefined Character is not in the string. +PANIC: None + + +Locates the character in AH within the string pointed to by SI in reverse order. + + +If the character is located then the index into the string is returned in AX. The index of the first character +in the string is 0. + + +This service is case independent. + + +¢ StringSubString Find a substring in a string +DS:SI Pointer to the string to be searched. +ES:DI Pointer to the string to be located. +RETURN: Carry clear +AX Offset of the substring in the string. +RETURN: Carry set +AL undefined Substring not found. + + +PANIC: None + + +Locates a string as a substring within another string. + + +If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index +of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string +is 0. + + +If the string is not a substring, then the service returns with the carry flag set. + + +This service is case dependent. + + +¢ StringSubStringFolded Find a substring in a string folded + + +DS:SI Pointer to the string to be searched. + +ES:DI Pointer to the string to be located. +RETURN: Carry clear + +AX Offset of the substring in the string. +RETURN: Carry set + +AL undefined Substring not found. + + +PANIC: None + + +Locates a string as a substring within another string. + + +If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index +of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string +is 0. + + +If the string is not a substring, then the service returns with the carry flag set. + + +This service is case independent and language dependent. + + +¢ StringLength Length of a string + + +ES:DI Pointer to the string whose length is to be found. +RETURN: +AX The length of string. + + +PANIC: None +Returns the length of the string pointed to by DI excluding the terminating zero. + + +18-4 + + +18 STRING MANAGEMENT + + +¢ StringValidateName Validate a system name +AL Maximum number of characters in the name allowed in the name. +AH Non 0 - An extension is valid. + + +0 - An extension is invalid. +ES:DI Pointer to the string to be validated. +RETURN: Carry clear +String is valid. +RETURN: = Carry set +NameErr String is not valid. +PANIC: None +Validates that the string at DI points to a valid system name. + + +An extension is only allowed if AH is non zero. AL specifies the number of characters that can be in the +name before the period. + + +The BNF for a valid name is as follows: + + +ANY := ALPHA | DIGIT | $ | _ +NAME := ALPHA [ [ANY]*7 [. [ANY]*3 ]] + + +18-5 + + +CHAPTER 19 + + +GENERAL MANAGEMENT + + +Version numbers + + +A version number is a 16 bit integer. If the 16 bit integer is converted to 4 hex digits, i.e. XY YZ, then the +version is: + + +X.YYZ + + +where X is the major release number, YY is the minor release number and Z is the version type. The +version type may have three values. + + +e A- Alpha release. +e 6B - Beta release. +e F - Final release. + + +Thus a typical version number 0x100f would be 1.00F. + + +GenVersion Get the operating system version number +None + +RETURN: +AX The operating system version number. + + +PANIC: None + + +Returns the operating system version number as a 16 bit integer. + + +GenRomVersion Get the ROM version number +None + +RETURN: +AX The ROM version number. + + +PANIC: None + + +Returns the ROM version number. + + +The operating system is never released on its own and is always supplied with a number of files in its built +in ROM disk. The tool which builds the operating system together with the ROM disk allows a version +number to be specified. This service can be used to retrieve the version number so specified. + + +19-1 + + +EPOC O/S SYSTEM SERVICES + + +GenLcdType Get the system LCD type + + +None +RETURN: +AL The LCD type. +PANIC: None +Returns the system LCD type. The various types are defined in epocdefs.inc. + + +GenStartReason Get the system cold start reason +None + +RETURN: +AL The cold start reason. + + +PANIC: None + + +Returns the system cold start reason. The operating system can perform a cold start for five reasons: +e Initialise; system RAM is invalid. +e Power fail; the system was forced to power down, but RAM is still valid. +e Reset; the user requested a reset, but RAM is still valid. +e =Kernel fault; a serious fault occurred while executing in the operating system kernel. + + +e New OSS restart; a new operating system has been programmed into the flash memory and a +restart has occurred. + + +The shell on first starting up should request the cold start reason and if it is not an initialise it should +inform the user of the reason for the cold start. + + +« GenDataSegment Get the operating system data segment +None + +RETURN: +ES The operating system data segment. + + +PANIC: None + + +Returns the operating system's data segment address. This service is reserved for use by system utilities. + + +GenGetCountryData Get the country data + + +BX Pointer to a cDataEnt structure. +RETURN: None +PANIC: None + + +Returns the country dependent data currently installed. The operating system on start-up copies the +country dependent data from the configuration file into RAM so that the GensetcountryData can be +called to update the information. + + +GenSetCountryData Set the country data + + +ES:BX Pointer to a cDataEnt structure. +RETURN: None +PANIC: None + + +Sets the country dependent data. The source of the data is the cbat arnt structure pointed to by ES:BX. + + +19-2 + + +19 GENERAL MANAGEMENT + + +GenGetOsData Get the O/S data + + +DI Pointer to a buffer to receive the data. +SI Offset in the operating system data space. +cx The number of bytes to be copied. + + +RETURN: None + +PANIC: None + +Copies data from the operating system's data space to the buffer provided. + +All operating system handles are the actual address in the operating system data space of the appropriate +control entry. For example, the handle returned by the Filzxecute service is the address in the operating + + +system data space of the z_proc process control entry. By fetching this data, a program can determine +many things about the state of a process. + + +GenGetErrorText Get error text +AL The error number. +BX Pointer to a buffer to receive the error text. + + +RETURN: None +PANIC: None + + +Returns the text associated with an error number. + + +The buffer pointed to by BX must be MaxErrorTextsize in length. If AL is not negative or it contains an +error unknown to the operating system, then "Unknown error [-xx]" will be returned where xx is the +unknown error number. + + +This is a language dependent service. + + +e Dummy Dummy service + + +None +RETURN: None +PANIC: None + + +This service provides a means for generating a call to a known location in the operating system. It is used +mainly for debugging the operating system. The service itself does nothing at all. + + +GenParse Generic file name parser + + +BX Pointer to a GenParseEnt Structure. +RETURN: Carry clear + +Success +RETURN: = Carry set + +NameErr Invalid name. +PANIC: None + + +This service provides a generic parse service which can be used to parse file names. + + +This service should not be confused with the rilparse service. FilParse Calls the file server which in +turn calls a file system to parse the file name and this will always be successful, assuming that the file +name obeys the naming rules for the target file system. + + +This service can only parse generic MSDOS like file names. The generic parser considers a file name to +consist of up to five components: + + +SystemName Drive Path Name Extension +A SystemName consists of a FileSystemName followed by two ':'s. + + +A Drive consists of a DriveName followed by DriveSeparator. + + +EPOC O/S SYSTEM SERVICES + + +A Path consists of a PathSeparator followed by zero or more DirectoryName PathSeparator pairs. +An Extension consists of an ExtensionSeparator followed by an ExtensionName. + + +The GenParseEnt structure allows a single character to be specified for each of the separators and the +maximum size for each of the four components. Note that the maximum size of a component includes any +separators. Note also that the SystemName separator of two ':'s cannot be specified. + + +For MSDOS filing systems, the values which should be loaded into the structure are as follows: + + +GenParseDeviceSeparator= ':' +GenParsePathSeparator= '\' +GenParseExtSeparator = +GenParseMaxDeviceSize= 2 + +GenParseMaxPathSize = 64 +GenParseMaxNameSize = 8 + + +vot + + +GenParseMaxExtSize = 4 + + +The remaining fields of the structure specify pointers to three input names, a pointer to the output buffer +and a pointer to a FullParseEnt Structure. + + +Parsing is effected as follows. The three input strings are prioritised in the order +GenParseSourceNamePtr,GenParseRelatedNamePtr and GenParseDefaultsPtr. Each of these input +strings is parsed into its four components (some of which may be missing). The resulting string is built by +taking components from the first string. Any missing components are filled in from the second string +(where they exist). Any components still missing are filled in from the third string. Thus, if the "source" +string does not have a drive, but the "related" string does, then the resulting name will use the drive as +specified in the "related" string. + + +When the resulting string has been built, the size of each component is put into the FullParseEnt +structure. + + +Finally, the name and extension components are examined for the wild card characters '?' and '*' and, if +found, the parseWildName and ParseWildext flags are set appropriately in the + +FullParseEnt .FullParseFlags field. If either parsewildName Of ParseWildExt is set then ParseWildAny +is also set. + + +GenDeferredMode Set deferred mode + + +AL 0 - Increment deferred mode. +Non 0 - Decrement deferred mode +RETURN: None +PANIC: None +This service only applies to the MC version of the operating system and can be used to defer some of the + + +work which is performed in the 32Hz. tick interrupt. + + +Calling the service with AL equal to zero will defer keyboard and mouse polling, parallel I/O polling and +the piezo sound system. This has the additional benefit of stopping the serial channel from being +temporarily diverted by the tick interrupt service routines. Normal operation can be resumed by calling +this service with AL set to a non zero value. + + +If the tick interrupt overhead must be reduced further then the anti-nesting flag can be incremented. This +is a byte at address 0438h in the operating system data space. While this flag is set, only the time is kept +up to date but be warned, pre-emptive multi tasking is disabled as are all timer services. + + +GenNotify Notify by text + + +BX Pointer to the first message. + +cx Pointer to the second message or zero. +Dx Pointer to the first option or zero. + +DI Pointer to the second option or zero. +SI Pointer to the third option or zero. + + +19-4 + + +19 GENERAL MANAGEMENT + + +RETURN: Carry clear +AL 0 - First option chosen by the user. +1 - Second option chosen by the user +2 - Third option chosen by the user. +RETURN: Carry set +FailErr No notify process running. +PANIC: None +This service will send a message to the notification process and await the result from the notifier, +returning the result in AL. If a notifier is not currently running then railerr will be returned. + + +BX and CX specify two zero terminated text messages which will be displayed by the notifier process. +Each string can be up to MaxNot ifyTextSize in length including the zero terminator. CX can be +optionally zero, in which case the second message line will be blank. + + +DX, DI and SI specify up to three options which the user may select. The selected option is returned in AL +and will be 0 if the DX option is chosen, 1| if the DI option is chosen and 2 if the SI option is chosen. By +convention, if all the options are specified as 0 then this is the same as having DX point to an option of +"CONTINUE". Each option string can be up to MaxOptionTextSize in length including the zero +terminator. Finally if DI is 0 then SI should also be 0. + + +The presentation of the notifier depends on the process which has hooked the notify interface. + + +GenNotifyError Notify by error number +AL The error number to be notified. +BX Pointer to the first message. +Dx Pointer to the first option or zero. +DI Pointer to the second option or zero. +SI Pointer to the third option or zero. +RETURN: Carry clear +AL 0 - First option chosen by the user. + + +1 - Second option chosen by the user. +2 - Third option chosen by the user. +RETURN: Carry set +FailErr No notify process running. +PANIC: None +This service first calls GenGetErrorText using AL as the parameter and then calls the GenNot ify service + + +with CX pointing to the resultant error text, all other registers being the same. + + +Only error numbers catered for by the configuration file should be notified using this service. It is +reasonable to expect that all errors returned by the operating system can be notified with this service. + + +GenNotifyHook Hook the notify interface + + +BX The message number. +RETURN: Carry clear +Success +RETURN: = Carry set +FailErr Notify interface already hooked. +PANIC: None +This service allows a process to get a message in response to calls by all other processes to the GenNotify + + +and GenNotifyError Services. + + +The message will be delivered with the message number specified in BX and the message buffer will +contain 5 words. The 5 words will consist of the 5 parameters to the GenNotify service in the order BX, +CX, DX, DI and SI. Note that as 5 words need to be delivered, a process which hooks the notify interface +should initialise messaging using the MessInit service with a size of at least 10 in BL. + + +19-5 + + +EPOC O/S SYSTEM SERVICES + + +The text string pointed to by the 5 parameters can be fetched from the requesting process using the +ProcCopyFromBylId service. The result should be returned in CX when the MessFree service is called to +give the result of the notification. + + +A process which has hooked the notify interface should not call either the Gennot ify or the +GenNotifyError services as it would then try and send itself a message, resulting in a lock up situation. It +is probably wise for the process to disable file server notifies for itself by calling the GensetNotifystate +to off, as it might be waiting for a file request to complete when the file server sends a notify message, +resulting in lock up. + + +If the process which has hooked the notify interface either exits or is panicked, then the supervisor will +automatically free the interface so that another process can hook it. + + +GenNotifyUnHook Unhook the notify interface + + +None +RETURN: None +PANIC: +PanicGenl Process does not have the interface hooked. + + +This service will release the notify interface provided the process calling this service already has the +interface hooked. If not, then the process will be panicked. + + +GenGetRamSizelnParas Get addressable system RAM size +None + +RETURN: +AX Size of system ram in paragraphs. + + +PANIC: None + + +Returns the size, in paragraphs, of the currently addressable system RAM. On machines containing more +than 512 kilobytes of RAM, this is not the same as the total amount of RAM that is fitted in the machine. + + +GenGetCommandLine Get the command line +None + +RETURN: +AX Pointer to the command line or 0. + + +PANIC: None + + +Returns a pointer to the command line. + + +The command line is a memory cell in the heap and can be freed if required with HeaprreeCell. +Processes can also be started with no command line in which case this service will return 0. + + +The address of the command line is also stored in the global variable ps: [Dat acommandPtr]. If the +command line is freed then, for consistency, this global variable should be set to 0. + + +The structure of the command line is a zero terminated string which contains the full path name used to +start the process. This can be used to find other files associated with the process being run or to open the +image file in order to access either added files or added DYLs. + + +After the 0 of the zero terminated string is a leading byte string containing any arguments for the process. +The string is leading byte counted so that binary arguments can be passed to programs. If the rFilExecute +service 1s called with CX equal to 0 then no command line is passed. This should only be used to execute +programs with no heap, since they obviously have nowhere to store the command line. It is preferable to +have CX pointing to a string containing just the zero terminator. + + +19 -6 + + +19 GENERAL MANAGEMENT + + +GenGetSoundFlags Get the sound flags + + +None +RETURN: +AX The sound flags. +PANIC: None +This service returns the current setting in the sound flags. The bits in the sound flags are as follows: + + +@® SoundKeyboardEnable - If set, will enable keyboard clicks. + +® SoundBuzzerEnable - If set, will enable the piezo sound system. +@® SoundDeviceEnable - If set, will enable the SND: device driver. +@ SoundLoud - If set, will make the piezo sound louder. + +® SoundDisable - If set, will disable all sound in the system. + + +GenSetSoundFlags Set the sound flags + + +BX The new sound flags. +RETURN: None +PANIC: None +This service sets the sound flags to the value in BX. The bits in the sound flags are as follows: + + +® SoundKeyboardEnable - If set, will enable keyboard clicks. + +@ SoundBuzzerEnable - If set, will enable the piezo sound system. + +@ SoundDeviceEnable - If set, will enable the SND: device driver. + +@ SoundLoud - If set, will make the piezo sound louder. + +® SoundDisable - If set, will disable all sound in the system. + +GenSound Make sound with the piezo + +BX The duration of the sound in ticks. +cx The pitch of the sound. + + +RETURN: None +PANIC: None + + +This service will make a sound through the piezo for the duration specified in BX ticks and at the pitch +specified in CX. The pitch can be calculated as (512/CX) KHz. The piezo uses very little power and is an +easy way of generating sound, although it is quite soft. If greater sound complexity, or a louder sound is +required then the SND: device driver can be used. + + +Access to this service is controlled by a semaphore which has been pre-counted with 1. When service is +requested, the semaphore is waited on and when completed the sound request is run. The service then +returns to the process requesting the service. When the duration elapses, the semaphore is signalled, +allowing the next service request to be processed. The effect of the above, assuming the piezo is not +already in use, is that the first call to this service will complete immediately allowing the application to go +about its business, but subsequent calls will wait until the current request is completed. If multiple +processes make requests on this service, they are run on a first come first served basis. + + +GenMarkActive Mark a process as active + + +None + +RETURN: None + +PANIC: None + +This service informs the operating system that the process invoking this service is to be considered active. +The operating system has the ability to auto switch off if no activity takes place within a certain length of + + +time. Activity is considered to be a context switch to a process which has been marked active, 1.e. +whenever the process executes, the timer controlling the auto switch off will be reset. + + +19-7 + + +EPOC O/S SYSTEM SERVICES + + +By default, all processes, when first created, are marked as active so that this service does not need to be +called unless the GenMarkNonAct ive service has been called. + + +GenMarkNonActive Mark a process as non-active + + +None +RETURN: None +PANIC: None + + +This service will inform the operating system that the process invoking this service is not to be considered +active. + + +The operating system has the ability to auto switch off if no activity takes place within a certain length of +time. Activity is considered to be a context switch to a process which has been marked active. Hence +marking a process as non-active will ensure that whenever the process executes, the timer controlling the +auto switch off will not be reset. + + +By default all processes, when first created, are marked as active so that this service must be called if the +process is not to be considered as active. All servers must mark themselves as non-active, since they only +execute when required by clients and the status of the client will determine activity or not. Thus if a client +of the file server is non-active and requests some file activity, it will not be considered as activity because +the file server is also marked as non-active. However if the client is active then by virtue of making the +request to the file server, the auto switch off timer will be reset. + + +If, for example, a program was left running displaying the time every second, by default, the machine +would never switch off as every second the process would execute resetting the auto switch off timer, +possibly not a desirable state of affairs. By marking the process as non-active then the activity of the +process would not reset the timer and the machine would be able to switch off. + + +GenGetText Get operating system text +AL The number of the text message to be retrieved. +ES:BX Pointer to the buffer to receive the text. + + +RETURN: Carry clear + +Success +RETURN: Carry set + +AL undefined Failed to find the message. +PANIC: None + + +This service will scan the operating system's built in configuration file for the text message associated +with the number in AL. This service is similar to GenGetErrorText when AL is negative but can also be +passed positive numbers. The text messages available depend entirely on the configuration file built into +the ROM with the operating system. + + +GenGetNotifyState Get notify state + + +None +RETURN: +AL The notify state. +PANIC: None +This service will get the current notify state for the process. +The file server, when it detects a problem which the user could possibly correct, will call the notifier + + +process to inform the user of the error and any action which must be performed (e.g. replacing an SSD +which had been accidentally removed before all files open on it were closed). + + +If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is +1 then the notifier will be called. + + +Some applications are intended to work in an unattended fashion so that a request for user attention would +be to no avail. In this case, the state should be set to 0 so that the process itself can take any action +required. By default, processes have the state set to 1. + + +19-8 + + +19 GENERAL MANAGEMENT + + +GenSetNotifyState Set notify state + + +AL The notify state. +RETURN: None +PANIC: None +This service will set the current notify state for the process. +The file server, when it detects a problem which the user could possibly correct, will call the notifier + + +process to inform the user of the error and any action which must be performed (e.g. replacing an SSD +which had been accidentally removed before all files open on it were closed). + + +If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is +1 then the notifier will be called. + + +Some applications are intended to work in an unattended fashion so that a request for user attention would +be to no avail. In this case, the state should be set to 0 so that the process itself can take any action +required. By default, processes have the state set to 1. + + +GenGetAutoSwitchOffValue Get the auto switch off time +RETURN: +AX The auto switch off time in seconds. + + +PANIC: None +This service can be used to get the current auto switch off time. +The time, in seconds, is returned in AX. It represents the amount of time which must expire with no + + +activity before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By +default, the auto switch off is set to 300 seconds. + + +GenSetAutoSwitchOffValue Set the auto switch off time + + +BX The auto switch off time in seconds. +RETURN: None +PANIC: None +This service can be used to set the auto switch off time. +The time, in seconds, is passed in BX. It represents the amount of time which must expire with no activity + + +before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By default, the +auto switch off is set to 300 seconds. + + +GenSetRevector Capture an interrupt +AL The vector number. +CX:BX The segment and offset on the interrupt routine. + + +RETURN: None +PANIC: None + + +The operating system hooks all interrupt vectors to itself and in the case of hardware interrupt vectors and +the special interrupt vectors, provides a shell interrupt service routine which will do all the right things to +satisfy the operating system rules. + + +This service allows a new interrupt service to be installed and should only be called by device drivers. As +the new interrupt service is being called by the operating service through a shell the following rules apply +to the interrupt service routine. + + +e All registers may be destroyed except BP,SP and SS. +e The routine should return with a far ret and not an iret. + + +e If a re-schedule is required, then it should return with carry set; if not then carry should be clear. + + +19-9 + + +EPOC O/S SYSTEM SERVICES + + +The interrupts which may be re-vectored in this way are specified by constants in epocdefs.inc and are as +follows: + + +@ HwIntORevector - Divide by zero interrupt. +@ HwInt1Revector - Single step interrupt. + +@ HwInt2Revector - Nmi interrupt. + +@ HwInt3Revector - Breakpoint interrupt. + + +@ HwInt4Revector - Bounds check interrupt. + + +e HwIrq0Revector - HwIrq7Revector - The 8 hardware interrupts. + + +Note that under no circumstances should the Nmi or Irq0 (the tick interrupt) interrupts be re-vectored. + + +GenResetRevector Release an interrupt + + +AL The vector number. +RETURN: None +PANIC: None + + +If the GensetRevector service has been used by a device driver to capture an interrupt, the interrupt +should be released using this service when no longer required. This allows the operating system to point +the vector to an appropriate default routine. The value in AL should be the re-vector number which was +originally passed to GenSetRevector. + + +GenGetLanguageCode Get the language code +None + +RETURN: +AX The language code. + + +PANIC: None + + +This service will return the language code for the configuration data built into the ROM with the +operating system. + + +Epoc is a configurable operating system and needs to be built with a configuration file using the +OSROM.EXE utility. Configuration files are language dependent and, as such, a language code is +included. The language code can be usefully used by applications which are multi-lingual to determine +which language to present. The language codes are as follows: + + += Test + += English += French += German += Spanish += Italian += Swedish += Danish += Norwegian + + +oMWAtInauw fF WNEFE OO + + += Finnish += American + += Swiss French += Swiss German += Portuguese +Turkish +Icelandic + + += Russian + += Hungarian + += Dutch + +9 = Belgian Flemish + + +AIHA BWNHEO +ll + + +20 = Australian + +21 = New Zealand + +22 = Austrian + +23 = Belgian French + + +19 - 10 + + +19 GENERAL MANAGEMENT + + +GenGetSuffixes Get suffix text + + +ES:BX Pointer to buffer to receive the suffix text. +RETURN: None +PANIC: None + + +This service will copy the language dependent suffixes from the configuration file into the buffer pointed +to by ES:BX. + + +The suffixes are fixed length zero terminated strings with a maximum length of three bytes including the +zero terminator. + + +Suffixes follow numbers for the day of the month (for example, the st in Ist. September 1990). Hence +there are 31 suffixes so that ES:BX must point to a buffer of at least 31*3 bytes. + + +This is a language dependent service. + + +GenGetAmPmText Get the AM and PM text + + +AL Zero - Get AM text +Non zero - Get PM text. +ES:BX Pointer to buffer to receive the AM and PM text. + + +RETURN: None +PANIC: None + + +This service will copy the language dependent "AM" and "PM" text from the configuration file into the +buffer pointed to by ES:BX. + + +The two text strings are fixed length zero terminated strings with a maximum length of three bytes +including the zero terminator. The "am" text is first, followed by the "pm" text. There are 2 strings of 3 +bytes each so that ES:BX must point to a buffer of at least 6 bytes. + + +This is a language dependent service. + + +GenGetBatteryType Get the battery type + + +None +RETURN: + +AL The battery type. +PANIC: None + + +This service gets the current battery type. + + +By default, Epoc sets the battery type to BatteryUnknown. The battery types are declared in the header file +epocdefs.inc. + + +On machines whose hardware does not support the detection of the battery type, a meaningful result +depends on a prior call having been made to GenSetBatteryType. + + +GenSetBatteryType Set the battery type + + +AL The battery type. +RETURN: None +PANIC: None + + +This service sets the current battery type. By default, Epoc sets the battery type to BatteryUnknown. The +battery types are declared in the header file epocdefs.inc. + + +Epoc needs to know about the various battery types because the levels at which low battery warning +messages are issued depends on the type. + + +If the battery type is BatteryUnknown then Epoc gives the same warning levels as for BatteryAlkaline. + + +A call to this function is not required on machines, such as the Workabout, whose hardware supports +detection of the battery type. + + +19-11 + + +EPOC O/S SYSTEM SERVICES + + +GenCrc Generate a CRC +cx The number of bytes in the buffer. +DX The current CRC. +DS:SI Pointer to the buffer to be CRC checked. +RETURN: +AX The updated CRC check. + + +PANIC: None + + +This service will generate a CRC polynomial checksum (X power 16 + X power 12 + X power 5 + 1, as +recommended by CCITT) from the buffer pointed to by DS:SI containing CX bytes. If the checksum is +being started then the value in DX should be passed as 0. + + +¢ GenintByNumber Interrupt by number +AL The interrupt number. +DS:SI Pointer to the input register values. +DS:DI Pointer to the output register values. +RETURN: +AX The flags register after the call. +PANIC: + + +Depends on the +interrupt called. + + +This service can be used to call any software interrupt and is provided to make calling the operating +system easier from high level languages. + + +The register values are stored sequentially as 6 words and represent the values for AX, BX, CX, DX, SI +and DI. BP is never needed by the operating system and so is not required. DS:SI and DS:DI can point to +the same memory location. The value returned is the flags register because although the carry flag is the +most important, some of the operating system routines also set the arithmetic flags. The carry flag is in bit +O of the returned result in AX. + + +GenEnvBufferGet Get environment variable +ES:DI Pointer to the environment variable name. +DL Length of environment variable name. +ES:SI Pointer to the buffer to receive the variable's value. +RETURN: Carry clear +AX The length of the data returned in ES:SI. +RETURN: Carry set +NotExistsErr No environment variable of the specified name exists. + + +PANIC: None + + +This service will locate an environment variable. The name of the variable is pointed to by ES:DI and has +a length of DL bytes. + + +The name may include wild cards, in which case the first matching name will be found. The value of the +environment variable is copied to ES:SI and the length of this data is returned in AX. + + +The maximum size of an environment variable's data is 255 bytes. + + +GenEnvBufferSet Set environment variable +ES:DI Pointer to the environment variable name. +DL Length of environment variable name. +ES:SI Pointer to the buffer containing the variable's data. +CL The length of the data as ES:SI. + + +19 - 12 + + +19 GENERAL MANAGEMENT + + +RETURN: = Carry clear + + +Success +RETURN: = Carry set +NoMemoryErr No space available to store environment variable. +FailErr Environment variable name contained wild cards. +PANIC: +PanicEnv0 DL exceeded MaxEnvNameSize + + +This service will either add or replace an environment variable. The name of the variable is pointed to by +ES:DI and has a length of DL bytes. + + +The name may not include wild cards nor exceed MaxEnvNameSize. The value of the environment variable +is pointed to by ES:SI and the length of the data to be copied is in CL. Since the data is a buffer of length +CL there is no restriction on what data may be placed in the buffer. + + +The maximum size of an environment variable's data is 255 bytes. + + +GenEnvBufferDelete Delete environment variable +ES:DI Pointer to the environment variable name. +DL Length of environment variable name. + + +RETURN: Carry clear +Success +RETURN: = Carry set +NotExistsErr No environment variable of the specified name exists. +PANIC: None +This service will delete an environment variable. The name of the variable is pointed to by ES:DI and has + + +a length of DL bytes. + + +The name may include wild cards in which case the first matching name is deleted. + + +GenEnvBufferFind Find environment variable +BX The find handle. +ES:DI Pointer to the environment variable name. +DL Length of environment variable name. +ES:SI Pointer to the buffer to receive the variable's data. +RETURN: Carry clear +AX The next find handle. +RETURN: Carry set +EofErr No more matching environment variables. + + +PANIC: None + + +This service will find all occurrences of environment variables which match the supplied wild card name. +The wild card name is pointed to by ES:DI and has a length of DL. + + +A wild card of "*" will locate all environment variables. When this routine is first called, BX must contain +zero; on subsequent calls, it must contain the value returned in AX. The wild card match string must +remain the same on successive calls. zofErr is returned when there are no more matching names. + + +After a successful call, the buffer pointed to by ES:SI contains two leading byte strings. The first string +contains the name of the environment variable while the second string contains its value. The maximum +size of an environment variable's data is 255 bytes. + + +19 - 13 + + +EPOC O/S SYSTEM SERVICES + + +GenEnvStringGet Get string environment variable +ES:DI Pointer to the environment variable name string. +ES:SI Pointer to the buffer to receive the variable's value. + + +RETURN: Carry clear +Success +RETURN: = Carry set +NotExistsErr No environment variable of the specified name exists. +PANIC: None +This service will locate an environment variable. The name of the variable is pointed to by ES:DI. The + + +name may include wild cards, in which case the first matching name will be found. + + +The value of the environment variable will be copied to ES:SI and will be zero terminated. Environment +variables should not include the byte 0 as this would terminate the string prematurely. The maximum +length of the string is 256 bytes including the terminating zero. + + +GenEnvStringSet Set string environment variable +ES:DI Pointer to the environment variable name. +ES:SI Pointer to the string containing the variable's data. + + +RETURN: Carry clear + + +Success +RETURN: = Carry set +NoMemoryErr No space available to store environment variable. +FailErr Environment variable name contained wild cards. +PANIC: +PanicEnv0 The name string exceeded MaxEnvNameSize + + +This service will either add or replace an environment variable. The name of the variable is pointed to by +ES:DI. The name may not include wild cards nor exceed MaxEnvNameSize. + + +The value of the environment variable is pointed to by the string at ES:SI. The maximum size of the string +should be limited to 255 bytes not including the zero terminator. Should the string be longer it will +truncated module 256. + + +GenEnvStringDelete Delete string environment variable + + +ES:DI Pointer to the environment variable name. +RETURN: Carry clear + +Success +RETURN: = Carry set + +NotExistsErr No environment variable of the specified name exists. +PANIC: None + + +This service will delete an environment variable. The name of the variable is pointed to by ES:DI. The +name may include wild cards in which case the first matching name is deleted. + + +GenEnvStringFind Find string environment variable +BX The find handle. +ES:DI Pointer to the environment variable name. +ES:SI Pointer to the buffer to receive the variable's name. +ES:CX Pointer to the buffer to receive the variable's data. +RETURN: Carry clear +AX The next find handle. + + +19-14 + + +19 GENERAL MANAGEMENT + + +RETURN: Carry set +EofErr No more matching environment variables. +PANIC: None +This service will find all occurrences of environment variables which match the supplied wild card name. + + +The wild card name is pointed to by ES:DI. A wild card of "*" will locate all the environment variables. + + +When this routine is first called, BX must contain zero; on subsequent calls it must contain the value +returned in AX. The wild card match string must remain the same on successive calls. EofErr is returned +when there are no more matching names. + + +After a successful call, the buffer pointed to by ES:SI contains the name of the environment variable +which was found, as a zero terminated string. The maximum size of the name of an environment variable +iS MaxEnvNameSize. + + +The buffer pointed to by ES:CX contains the value of the environment variable which was found, as a zero +terminated string. The maximum size of the data is 256 bytes, including the zero terminator. + + +GenAlarmHook Hook the alarm interface + + +BX The message number. +RETURN: Carry clear +Success +RETURN: Carry set +FailErr Alarm interface already hooked. +PANIC: None +This service allows a process to capture the alarm interface built into the operating system. Having hooked + + +the alarm interface the ALM: device driver can be used to request alarms from the alarm server. + + +The availability of an alarm server and what it does, varies from machine to machine and the appropriate +documentation for the specific machine should be consulted. + + +GenAlarmUnHook Unhook the alarm interface +None + +RETURN: None + +PANIC: +PanicGenl Process does not have the interface hooked. + + +This service will release the Alarm interface if the process calling this service already has the interface +hooked. If it does not, the process will be panicked. + + +GenAlarmld Get the pid of the alarm server + + +None +RETURN: + +AX The alarm server pid. +PANIC: None + + +This service will return the ID of the alarm server. If the alarm interface is not currently hooked then this +service will return zero in AX. + + +GenTickle Reset the auto switch off timer + + +None +RETURN: None +PANIC: None + + +This service will reset the auto switch off timer to the value as specified to the last +GenSet Aut oSwitchOffValue. This routine is useful for processes which have called GenMarkNonAct ive +and require to "tickle" the auto switch off from time to time. + + +19 - 15 + + +EPOC O/S SYSTEM SERVICES + + +GenSetOnEvents Control on events + + +AL The find handle. +RETURN: None +PANIC: None + + +This service controls whether the system will report on-events(for example, reporting to the window +server when the machine switches on). If AL is non-zero then on-events will be reported. If AL is zero, +they will not. + + +By default on-events are reported on Series 3 and Series 3a operating systems and not reported on other +versions. + + +©GenGetAutoMains Get state for auto-sw-off if mains present +RETURN: + + +AX The current auto-switch-off state for when mains is present. +PANIC: None + + +Returns a non-zero value in AX if auto-switch-off is disabled when mains is present, and zero if enabled. + + +©GenSetAutoMains Disable/enable auto-sw-off if mains present + + +AL Flag specifying whether to enable or disable. +RETURN: None +PANIC: None + + +Enable or disable auto-switch-off if mains is present. If AL is non-zero, auto-switch-off is disabled, +otherwise it is enabled. + + +By default auto-switch-off is enabled. + + +Even if enabled, the machine will not switch off when mains is absent if auto-switch-off has been stopped +by calling GensetAutoSwitchOffValue with value -1. + + +19 - 16 + + +CHAPTER 20 + + +DATABASE FILE MANAGEMENT + + +File structure + + +Database files (DBFs) start with a 22 byte header which contains the following information: + + +Offset in header Information + +0 - 15 Zero terminated file signature. + +16, 17 Version of DBF software used to produce the file. +18, 19 Offset from the start of the file to the first record. +20, 21 Minimum version of DBF software required. + + +Note that all 16 bytes of the file signature are used for verification, not just the zero terminated string. +Therefore it is recommended that all file signatures are padded with zeros to fill the 16 bytes. + + +See the Dbfversion service for the format of the version numbers. + + +The offset within the file of the first record is to allow additional information to be added to the header +(called the Extended Header). Note that the first record will always be a type 2 record - see below. + + +The data consists of records, each with a 2 byte header stored as a word. The high nibble of the most +significant byte (i.e. the 2nd byte in the record) gives the record's type. This can take the following values: + + +0 A deleted record. + +1 A main record. + +2 The Field Information Record. + +3 The Descriptive Record. + +4-7 Reserved for record types which won't be merged. +8 - 13 Reserved for record types which will be merged. +14 Reserved for voice entries. + +15 Used internally (not to be used by applications). + + +Note that types 8 - 14 will be copied and merged by the pbfcopyFile service when DbfRecordTypeAl1l is +specified whereas record types 3 - 7 will only be copied if the target file is created, i.e. not if merging two +files. + + +The remaining 12 bits of the header word give the size of the record. However the maximum size of a +record is 4094 bytes, so that there is room in a 4096 byte buffer for the longest record including its header. + + +The Field Information Record is used to store the field structure used by the other records. There will +be exactly | Field Information Record per file and it will always be the first record in the file (any other +type 2 records will be ignored). Each byte in the record indicates the type of the corresponding field in the +records which follow, so the length of this record is the number of fields. The possible values for each byte +are: + + +0 Word +1 Long + + +20-1 + + +EPOC O/S SYSTEM SERVICES + + +2 Double +3 String +4 - 255 Reserved + + +The maximum length of this record is 32 bytes representing 32 fields. + + +The 22 byte header and the Field Information Record must be passed to the Dpbfopen service when a file +is created or replaced and will be returned by pbfopen when an existing file is opened. + + +Buffering + + +When a database file is opened, the address of a buffer must be provided which should be at least as large +as the maximum record size to be used. Thus, a buffer of 4096 bytes is guaranteed to open all database +files. This buffer will be used to read this many bytes worth of records from the File System at a time so as +to reduce the calls to the File System and vastly increase the speed of operation of most of the DBF +services. + + +If the buffer provided is smaller than 4096 and there are records which are longer than the buffer, an error +will be given when the file is opened. + + +Note that the read services simply return the offset of the record within the buffer. If the buffer needs to +be used by the application, e.g. for editing a record, the DpfcopyDown service should be called to copy the +current record to the start of the buffer and to signal that the buffer is invalid. The pbftrash service +simply marks the buffer as invalid. These two services will therefore cause the entire buffer to be read in +the next time a record is read, inevitably resulting in a loss of performance. + + +All DBF services may overwrite the buffer containing the current record apart from the following: + + +DbfFlush +DbfVersion +DbfAppend +DbfSense +Dbf£Count + + +which are guaranteed not to alter the buffer. + + +Index Table + + +In addition to buffering, a sparse index table consisting of a 4 byte address for every 16 records will be +constructed when the file is opened to increase the speed of random access to the file. As records are +added to the file, the table will also be appended. When a record is deleted, each pointer in the table after +the deleted record will be moved to the next record, so that they always point to every 16th record. Note +that the index table will reside in a different segment so as not to use up the application's space. + + +End of file record + + +When any of the record services attempt to read past the end of the file, zofzrr will be returned and the +current record number will be the number of the last record plus 1. Also, attempting to read before the +first record in the file, either with the DpfBackRead Service or the DbffrindRead Service searching +backwards will result in zofErr and the current record number will be zero (i.e. the first record if there is +one). However the offset in the buffer of the first/last record will not be returned, when £ofeErr is returned. + + +The "current record" is always given by the record number returned by the pbfsense service but if any +service gives EofErr, the current record will be the last record number plus | - this is called the end of +file record (unless the error is caused by going before the first record). When this is the case, any services +which work on the current record, e.g. DbfEraseRead, DbfUpdate, DbfFindRead searching forwards will +return EofErr. Similarly if there are no records in the file, ppfsense record will return 0 but the above +services will return EofErr. + + +20 DATABASE FILE MANAGEMENT + + +Number of records + + +The maximum number of records which can be present is 65534 and they are numbered from 0 to 65533. +An error will be given by the ppfappend service if an attempt is made to write more than 65534 records. + + +DbfOpen Open a database file + + +CL Type of record. + +SI Pointer to the main buffer. + +DI State. + +Dx Length of the main buffer. + +BX Points to a DbfopenkEnt Structure containing the remaining +parameters. + + +RETURN: Carry clear + + +DI State. +RETURN: Carry set +RecordErr There are records longer than buffer supplied or buffer length is +invalid. +InvalidFileErr The file is not a valid DBF file. +PANIC: +None + + +This service works in the same way as the standard file open service with the following features: + + +e The service can be called in a loop with DI equal to pbfstatestart the first time and then passed +as it is returned until it becomes ppbfstatestart again or alternatively if DI is passed as +Dbf£StateDisabled, the service will not return until it has finished. + + +Also DI can be passed as pbfst at eOpenNoIndex to disable the building of the index. This means +it will be faster to open, but only the following services can be used on a file opened this way: +DbfClose, DbfFlush, DbfTrash, DbfCopyDown, DbfCopyFile, DbfAbsRead, DbfAbsReadSense, +DbfNextRead, DbfBackRead, DbfFirstRead, DbfSense. Note that reading records non-sequentially +will be much slower than when the file is opened with index building. Calls to any other services +will produce unpredictable results. + + +e The pbfopenmode field of the ppfopenkEnt structure need not specify the file format. The DBF +file format will be assumed. If a file is created or replaced, modeUpdate must be specified since +the header is written to the file. + + +e The pbfopenHeader field of the ppfopenknt structure is a pointer to a 56 byte buffer. The header +consists of the 22 byte header described above followed immediately by the Field Information +Record as a type 2 record. The maximum length of the Field Information Record is 32, plus its +2 byte header = 34. Therefore the buffer must be 22 + 34 = 56 bytes. Even if an Extended Header +is required, no gap should be left in the header when creating a file and no gap will be returned +when opening an existing file. The file itself, however will contain a gap for the Extended +Header, the length of which can be calculated from the 'start of data’ field in the 22 byte header. + + +When opening an existing file, the header buffer must contain the file signature which will be +verified against the signature in the file and InvalidrileErr will be returned if it is not identical. +Note that all 16 bytes of the signature are always checked, not just the zero terminated string. +The remainder of the header buffer will be filled in. Note that the type 2 record is not verified to +be the same as the header and so need not be supplied. + + +When creating or replacing a file, the header buffer must contain all 56 bytes to be written to the +file as a header. + + +EPOC O/S SYSTEM SERVICES + + +In both the above cases, the minimum version number at offset 20 in the header will be checked +and InvalidFileErr returned if this DBF software cannot handle it. See the pbfversion service +for the format of the version numbers. Note that only the major version number is checked (i.e. +the most significant 4 bits only of the version number word. Also, the type 2 record is checked to +be valid and invalidFileErr returned if it is not. + + +e The main buffer at SI is used to read DX bytes worth of records at a time from the File System. +e CL specifies the type (0 - 14) of records to be accessed (it will usually be 1). + + +e A sparse index table consisting of a 4 byte address for every 16 records will be constructed when +the file is opened to increase the speed of random access to the file. This will reside in a separate +segment so as not to use any of the application's space. + + +Note that after opening the file, the current record number will be 0 (as returned by pbfsense) so that a +call to DbfNext Read would read record number | in the file and pbfEraseRead would erase record 0. +DbfFirstRead should be called to read record 0. + + +The length of buffer supplied must be in the range 512 to 16384. Any length outside this range will result +in RecordErr when the file is opened. The maximum length of a record is 4094 bytes, so there is always +room in a 4096 byte buffer for all records (including the 2 byte header). + + +DbfClose Close a database file +BX The DBF handle to be closed. +RETURN: Carry clear +Success +RETURN: Carry set +AL Error number. +PANIC: +PanicDbf1l BX is not a valid DBF handle. + + +Closes a database file. + + +The handle must be one returned from the ppfopen service. + + +DbfFlush Flush a database file + + +BX The DBF handle. +RETURN: Carry clear + + +Success +RETURN: Carry set +AL Error number. +PANIC: +PanicDbf1 BX is not a valid DBF handle. + + +Flushes all buffers. + + +DbfTrash Trash a database file + + +BX The DBF handle. +RETURN: None +PANIC: +PanicDbf1 BX is not a valid DBF handle. + + +Signals that the main database file buffer is no longer valid, so that it can be used by an application. See +also the Db£fCopyDown Service. + + +20-4 + + +20 DATABASE FILE MANAGEMENT + + +DbfCopyDown Copy down a DBF record + + +BX The DBF handle. + +SI The offset into the main buffer of the record to copy down. +RETURN: + +AX The length of the record copied down. +PANIC: + +PanicDbfl BX is not a valid DBF handle. + +PanicDbf2 SI is not a valid offset. + + +Copies a record at the given offset in the main buffer down to the start of the buffer and sets a flag to +signal that the buffer is no longer valid (i.e. there is no need to call ppbftrash). The length of the record is +read from the buffer and is returned by the service. + + +DbfCompress Compress a database file +BX The DBF handle. +DI State. +RETURN: Carry clear +DI State. +RETURN: Carry set +AL Error number +PANIC: +PanicDbf1 BX is not a valid DBF handle. + + +Recovers space used by deleted records provided the file is stored on a compressible media. If the media is +not compressible, this service will do nothing and will return carry clear. + + +After calling this service, the current record will be the end of file record (unless the media was not +compressible - in which case the current record is unchanged). + + +DI can be passed as pbfStateStart Or DbfStateDisabled. If it is passed as ppfstatestart, the service + + +must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, +the service will not exit until it is finished. + + +DbfCopyFile Copy a database file + + +BX The DBF handle. +CL Record type to copy. +CH The direction of the copy (to or from the target file). +Dx Open mode for target file. +DI State. +SI Pointer to the target file name. +RETURN: Carry clear +DI State. +RETURN: Carry set +AL Error number. +PANIC: +PanicDbfl BX is not a valid DBF handle. + + +Copies records except deleted records from or to the open source file. This service will append records to +the end of an existing file if DX is Modeopen or ModeAppend. Note that ModeAppend will perform exactly +the same as ModeOpen. Copying with ModeUnique will copy the records to a unique file and return the +name in the buffer at SI, in exactly the same way as Dbfopen. Note that the source file can be opened with +index building disabled, i.e. with DI as ppfstateopenNoIndex with no loss in performance of the copy. + + +20-5 + + +EPOC O/S SYSTEM SERVICES + + +CL is used to specify the type of record to be copied. If ppfRecordTypeall is specified, all record types +will be copied. Note that when merging files (i.e. DX is Modeopen Of ModeAppend) with +DbfRecordTypeA11, only record types | and 8 - 14 will be copied across. Record types 2 - 7 will not be +copied. Record type 2 is the Field Information Record and record type 3 is the Descriptive Record +and types 4 - 7 are reserved for future use. Record types 2 - 7 will be copied if DX is Modecreate, +ModeReplace Of ModeUnique. + + +CH must be passed as pbfCopyFromHandle to copy from the open file to the named file or +Dbf£CopyToHandle to copy the other way. Note that in the latter case DX must obviously be passed as +Modeopen. Note that it is always slower using DpbfCopyToHandle because of the need to update the index +table for the open file. + + +The following procedure is used to implement the copy: + + +e The target file is opened in the mode specified. If copying to an existing file, the signatures of the +two files are verified and the r1r's are checked to be compatible. If copying to a new file, the +header (including the rrr) and any Extended Header are copied from the source file to the target +file. + + +e All records of the specified type are copied from the source file to the target file. +e = The target file is closed. + + +e = If any error occurs during the above procedure and the target file has been created by +Db£CopyFile, the target file will be deleted, if possible. + + +DI can be passed as DbfStateStart, DbfStateDisabled Of DbfStateCopyAbort: +e If it is passed as DbfstateDisabled the service will not exit +until it is finished. + + +e If it is passed as pbfstatestart the service must be called repeatedly until state becomes +DbfStateStart again. This parameter can be used to plot the progress of the copy, for example +by drawing a bar graph. DI will be incremented for every 'buffer size’ number of bytes that are +copied (approximately). Hence the scale of the graph can be calculated by dividing the size of the +file by the buffer size allocated. The graph plotting procedure must take account of the error in +the number of times required to call the service. A fudge factor of 2 should be added to calculate +how many times the service will be needed to be called. + + +e Di can be passed as DpbfstateCopyAbort to abort the copy which was started with +DbfStateStart. + + +Warning: using DbfCopyFile to merge files can result in a file with more than 65534 records of a +particular type in it. When this file is opened with the pbfopen service, only the first 65534 records will be +accessible. No error is given from the copy or the open. + + +DbfFileSize Get the size of a DBF + + +BX The DBF handle. +RETURN: Carry clear + +DI:DX The file size in bytes. +RETURN: Carry set + +AL Error number. +PANIC: + +PanicDbfl BX is not a valid DBF handle. + + +Gets the size of an open database file. + + +20 - 6 + + +DbfExtHeaderRead + + +AL + + +BX +ex +SI + +RETURN: Carry clear +AX + +RETURN: Carry set +EofErr + +PANIC: + + +PanicDbf1 + + +20 DATABASE FILE MANAGEMENT + + +Read a DBF extended header + + +0 to start + +1 to continue. + +The DBF handle. + +The number of bytes to read. + +The address of the buffer to receive the data. + + +The number of bytes actually read. +The end of the Extended Header has been reached. + + +BX is not a valid DBF handle. + + +Reads CX bytes from the Extended Header of a database file into the buffer supplied. + + +AL must be passed as 0 the first time and 1| to continue. + + +EofErr is returned when the end of the Extended Header is reached, otherwise the actual number of bytes + + +read is returned. + + +DbfExtHeaderWrite + + +AL + + +BX +CX +SI + +RETURN: Carry clear +AX + +RETURN: Carry set +EofErr + +PANIC: + + +PanicDbf1 + + +Write a DBF extended header + + +0 to start + +1 to continue. + +The DBF handle. + +The number of bytes to write. + + +The address of the buffer containing the data to write. +The number of bytes actually written. +A write past the end of the Extended Header was attempted. + + +BX is not a valid DBF handle. + + +Writes the buffer supplied into the Extended Header of the file. + + +AL must be passed as 0 the first time and 1 to continue. + + +EofErr is returned when the end of the space allocated for the Extended Header is reached, otherwise the +actual number of bytes written is returned. + + +DbfDescRecordRead + + +BX + +RETURN: Carry clear +AX + +RETURN: Carry set +EofErr + +PANIC: + + +PanicDbf1 + + +Read a DBF descriptive record +The DBF handle. + + +The length of the Descriptive Record +There is no Descriptive Record in the file. + + +BX is not a valid DBF handle. + + +Reads the Descriptive Record into the main buffer at offset zero. If there is no Descriptive Record, + + +EofErr Will be returned. + + +20-7 + + +EPOC O/S SYSTEM SERVICES + + +DbfDescRecordWrite Write a DBF descriptive record +BX The DBF handle. +cx The length of the Descriptive Record to be written. + + +RETURN: Carry clear + + +Success +RETURN: = Carry set +AL Error number. +PANIC: +PanicDbf1 BX is not a valid DBF handle. + + +Writes out a Descriptive Record. The record to be written must be stored at the start of the main buffer +as a DbfRecord Structure; there must be 2 bytes before the data starts where the record header will be +constructed. See pbfAppend. + + +Any existing Descriptive Record will be erased, in other words, there can be a maximum of one +Descriptive Record per file. + + +If CX is passed as zero, any existing Descriptive Record Will be erased and no new one will be written +out. If there is no Descriptive Record, no error is given. + + +DbfVersion Get the DBF version number +None + +RETURN: +AX The DBF version number. + + +PANIC: None + + +Gets the version number of the DBF software. This will be in the form: + + +XYYF +where + +x is the major version number (4 bits) + +YY is the minor version number (8 bits) + +F is the release type, either A,B or F for Alpha, Beta or Final + + +respectively (4 bits). +For example, if 110FH is returned, the DBF software version is 1.10F. + + +Note that only the major version number is used to determine whether or not the DBF file system can +handle a particular file. + + +DbfAbsRead Read an absolute DBF record + + +BX The DBF handle. +ex The absolute record number to be read. +RETURN: Carry clear +AX The length of the record read. +SI The offset in the main buffer of the record read. +RETURN: Carry set +EofErr The requested record number is greater than the number of records +in the file. +PANIC: +PanicDbfl BX is not a valid DBF handle. + + +This service will seek to the given record and read it. Records are read into the buffer (supplied when the +file was opened) and the record's offset within the buffer is returned in SI. + + +If the record number requested corresponds to a record beyond the last one, the error zofErr will be +returned, the current record will be the end of file record and SI will be invalid. + + +20-8 + + +DbfAbsReadSense + + +BX +CX + +RETURN: Carry clear +AX +SI +DI:DX + +RETURN: Carry set + + +EofErr + + +PANIC: + + +PanicDbf1 + + +20 DATABASE FILE MANAGEMENT + + +Read and sense an absolute DBF record +The DBF handle. + + +The absolute record number to be read. +The length of the record read. +The offset in the main buffer of the record read. + + +File position of start of record. + + +The requested record number is greater than the number of records +in the file. + + +BX is not a valid DBF handle. + + +Same as the pbfabsRead Service but also returns the file position of the start of the record. + + +DbfNextRead + + +BX + +RETURN: Carry clear +AX +SI + +RETURN: Carry set +EofErr + +PANIC: + + +PanicDbf1 + + +Read the next DBF record +The DBF handle. + + +The length of the record read. + + +The offset in the main buffer of the record read. +The current record was already the last record in the file. + + +BX is not a valid DBF handle. + + +Seeks to the next record and reads it. Records are read into the buffer (supplied when the file was opened) +and the record's offset within the buffer is returned in SI. + + +If the current record is already the last record in the file or there are no records of the current type in the +file, EofErr will be returned, the current record will be the end of file record and SI will be invalid. + + +DbfBackRead + + +BX + +RETURN: Carry clear +AX +SI + +RETURN: Carry set +EofErr + +PANIC: + + +PanicDbf1 + + +Read the previous DBF record +The DBF handle. + + +The length of the record read. + + +The offset in the main buffer of the record read. +The current record was already the first record in the file. + + +BX is not a valid DBF handle. + + +Seeks to the previous record and reads it. Records are read into the buffer provided when the file was +opened and the offset into this buffer of the record required is returned in SI. + + +If, on entry to the call, the current record is already the first record in the file or there are no records of the +current type in the file, Eofzrr will be returned, the current record will be 0 and SI will be invalid. + + +20-9 + + +EPOC O/S SYSTEM SERVICES + + +DbfFirstRead Read the first DBF record + + +BX The DBF handle. +RETURN: Carry clear + +AX The length of the record read. + +SI The offset in the main buffer of the record read. +RETURN: Carry set + +EofErr There are no records in the file. +PANIC: + +PanicDbf1 BX is not a valid DBF handle. + + +Seeks to the first record and reads it. Records are read into the buffer (supplied when the file was opened) +and the record's offset within the buffer is returned in SI. + + +If there are no records in the file of the current type, zoferr will be returned, and SI will be invalid. + + +DbfLastRead Read the last DBF record + + +BX The DBF handle. +RETURN: Carry clear + +AX The length of the record read. + +SI The offset in the main buffer of the record read. +RETURN: Carry set + +EofErr There are no records in the file. +PANIC: + +PanicDbf1l BX is not a valid DBF handle. + + +Seeks to the last record and reads it. Records are read into the buffer (supplied when the file was opened) +and the record's offset within the buffer is returned in SI. + + +If there are no records in the file of the current type, zofErr will be returned, and SI will be invalid. + + +DbfAppend Append a DBF record + + +BX The DBF handle. +CX The length of the record to be appended. +RETURN: Carry clear +Success +RETURN: = Carry set +OverFlowErr There are already 65534 records in the file. +RecordErr The total length of the record (including the 2 byte header) is +greater than the length of the main buffer. +PANIC: +PanicDbfl BX is not a valid DBF handle. + + +This service appends a record of the current type to the end of the file and makes this the current record. + + +The record to be written must be placed at the start of the main buffer as a pbfRecord structure which is +defined as: + + +typedef struct +{ +UWORD header; /* Used for record header word */ +UBYTE data[2]; /* Data to be written... * f +} DbfRecord; + + +The header word will be used to construct the header for the record so that it can be written in one. + + +CX is the length of the data only. + + +20 - 10 + + +20 DATABASE FILE MANAGEMENT + + +DbfEraseRead Erase a DBF record + + +BX The DBF handle. +DI State. +RETURN: Carry clear +AX The length of the record read. +SI The offset in the main buffer of the record read. +DI State. +RETURN: Carry set +EofErr The current record is the end of file record. +PANIC: +PanicDbf1 BX is not a valid DBF handle. + + +Erases the current record and reads the next one. + + +A record is erased by overwriting its (4 bit) type to 0. The space used by the record can only be recovered +by calling ppfcompress. The file must be stored on a compressible medium. + + +If there are no records of the current type in the file or if the current record number is the last record plus +1, EofErr will be returned. If the current record is the last record in the file, it will be erased and zofErr +will be returned. + + +Note that pbfEraseRead may return EofErr in 2 different circumstances: +e If the current record is already the end of file record (or there are no records). +e If the current record is the last record. + + +In the first case, the service does nothing. In the second case, the last record is erased and the current +record becomes the end of file record. It is up to the application to deduce which of these cases has +occurred by checking whether the current record is the end of file record before calling the service +(using DbfSense and DbfCount) or by noting the decrease in the total number of records from pbfcount. + + +DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service +must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, +the service will not exit until it is finished. + + +DbfUpdate Update a DBF record + + +BX The DBF handle. + +CX The length of the record to be written. + +DI State. +RETURN: Carry clear + +DI State. +RETURN: Carry set + +EofErr The current record is the end of file record. +PANIC: + +PanicDbf1 BX is not a valid DBF handle. + + +Erases the current record and appends the new one to the end of the file making this the new current +record. The new record to be appended will be taken from the beginning of the main buffer. + + +The main buffer must begin with a word where the record header will be built, followed by the record +itself. + + +CX is the length of the data only and does not include the word at the start. +Note that the current record will only be erased after the supplied record has been successfully appended. + + +If there are no records of the current type in the file or if the current record number is the last record plus +1, EofErr will be returned. If the current record is the last record in the file, it will be erased and £oferr +will be returned. + + +20 - 11 + + +EPOC O/S SYSTEM SERVICES + + +DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service +must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, +the service will not exit until it is finished. + + +DbfFindRead Find a DBF record + + +AL The number of fields to search. +BX The DBF handle. +Cx The length of the buffer to match. +DL The maximum field length to match with. +DH The type and direction of the search. +DI State. +SI Pointer to the match buffer. +RETURN: Carry clear +AX The length of the record read. +DI State. +SI The offset in the main buffer of the record read. +RETURN: Carry set +EofErr No matching record was found. +PANIC: +PanicDbfl BX is not a valid DBF handle. +PanicDbf2 Parameters are invalid. + + +Matches the given wild-card string with the string components of each record starting at the current +record. If the current record is the end of file record, EofErr will be returned, unless DH specifies +DbfFindBackwards. + + +If a match is found, the record containing the match is made the current record and is read into the buffer; +the offset will be returned in SI. + + +AL specifies how many string fields are to be searched (the number of string fields in the Field +Information Record is now irrelevant). A value of DpfFindAllstrings must be used to specify continue +matching string fields until the end of the record is reached. The Field Information Record Is used to +specify the 'types' of the first 32 fields. After that, all fields are assumed to be strings until the end of the +record. + + +DL specifies the maximum length of a string field to be used in the match, i.e. longer strings are truncated +for matching purposes. 255 specifies no truncation. + + +DH is split into 2 halves. +The most significant nibble of DH specifies the type of match and must be one of the following: + + +DbfFindCaseIndependent Case independent match. +Dbf£fFindCaseDependent Case dependent match. + + +The least significant nibble of DH specifies the search direction and must be one of the following: + + +DbfFindForwards Search forwards from current record to next match. +DbfFindBackwards Search backwards from current record to previous match. +DbfFindFirst Search to first match in file. + +DbfFindLast Search to last match in file. + + +If a match is not found, zoferr will be returned and SI will be invalid. The current record will then be the +first record if the search was backwards or the last record number plus one (the end of file record) if the +search was forwards. + + +The Field Information Record contains the record structure which is used to find the string components +of the record. This is always passed to pbfopen as part of the header when a file is created and is returned +when an existing file is opened. + + +DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service +must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, +the service will not exit until it is finished. + + +20 - 12 + + +20 DATABASE FILE MANAGEMENT + + +DbfSense Sense the current DBF record number +BX The DBF handle. + +RETURN: +AX The current record number. + + +PANIC: None + + +Sense the current record number. This will be the last record number plus 1 if an EofErr has just been +given (unless there are no records, in which case it will be 0). + + +DbfCount Count the number of DBF records +BX The DBF handle. + +RETURN: +AX The number of records of the current type. + + +PANIC: None + + +Returns the number of records in the file of the current type. It will not alter the current record number. + + +©DbfFindReadField Find a DBF record by field + + +AL The number of fields to search. + +BX The DBF handle. + +cx The length of the buffer to match. + +DL The maximum field length to match with. + +DH The type and direction of the search. + +DI State. + +SI Pointer to the match buffer. + +DatEClassPtr The starting field from which to search (0 for first field) +RETURN: = Carry clear + +AX The length of the record read. + +DI State. + +SI The offset in the main buffer of the record read. +RETURN: Carry set + +EofErr No matching record was found. +PANIC: + +PanicDbfl BX is not a valid DBF handle. + +PanicDbf£2 Parameters are invalid. + + +Matches the given wild-card string with the string components of the specified fields in each record +starting at the current record. If the current record is the end of file record, FofErr will be returned +unless DH specifies pbfFindBackwards. + + +This service is the same as DbfFindRead except that DatEClassPtr specifies the starting field from which +the search starts (with 0 specifying the first field). For example, to search only the third, fourth and fifth +text fields, set patEClassPtr to 2 and AL to 3. + + +20 - 13 + + +20 - 14 + + +CHAPTER 21 + + +HARDWARE MANAGEMENT + + +HwComboOn Switch on the combo + + +None +RETURN: None +PANIC: None +This service will switch on the combo hardware subsystem (CHS) if not already switched on. +Although the CHS has been enabled, it can be accessed either by an external expansion device or by +Asicl. If it is desired to access the CHS using Asicl then the SLDTX bit in the Asic! Control register + + +needs to be enabled as well. Before turning the CHS on, it is important to see if it is available for use by +calling the HwGet Combo service. + + +This service is equivalent to HwComboOnInput for all variants except Asic9 variants (Series 3a). On Asic9 +variants HwComboOn puts the codec into output mode, while HwcComboonInput puts it into input mode. + + +HwComboOftf Switch off the combo + + +None +RETURN: None +PANIC: None + + +This service will switch off the combo hardware subsystem (CHS) if not already switched off. + + +HwPacksOn Switch on the SSDs + + +None +RETURN: None +PANIC: None +This service will switch on the SSD subsystem (SSDS) if not already switched on. + + +This service is provided for the built in SSD drivers and should not be called by any other drivers or +applications. + + +HwPacksOff Switch off the SSDs + + +None +RETURN: None +PANIC: None +This service will switch off the SSD subsystem (SSDS) if not already switched off. + + +This service is provided for the built in SSD drivers and should not be called by any other drivers or +applications. + + +21-1 + + +EPOC O/S SYSTEM SERVICES + + +HwSetA2Control1Bits Set bits Asic2 register 1 + + +AL Mask of bits to be set. +RETURN: None +PANIC: None + + +This service can be used to set bits in Asic2 control register 1. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit which is set in the mask will cause the corresponding bit in the control register to be set. + + +HwClearA2Control1 Bits Clear bits Asic2 register 1 + + +AL Mask of bits to be cleared. +RETURN: None +PANIC: None + + +This service can be used to clear bits in Asic2 control register 1. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit which is set in the mask will cause the corresponding bit in the control register to be cleared. + + +HwReadA2Control1 Read Asic2 register 1 + + +None +RETURN: + +AL The value currently in control register 1. +PANIC: None + + +This service can be used to read Asic2 control register 1. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it returns the value in its up-to-date copy. + + +HwWriteA2Control1 Write Asic2 register 1 + + +AL The new value to be written to control register 1. +RETURN: None +PANIC: None + + +This service can be used to write to Asic2 control register 1. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. + + +HwSetA2Control2Bits Set bits Asic2 register 2 + + +AL Mask of bits to be set. +RETURN: None +PANIC: None + + +This service can be used to set bits in Asic2 control register 2. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit set in the mask will cause the corresponding bit in the control register to be set. + + +21-2 + + +21 HARDWARE MANAGEMENT + + +HwClearA2Control2Bits Clear bits Asic2 register 2 + + +AL Mask of bits to be cleared. +RETURN: None +PANIC: None + + +This service can be used to clear bits in Asic2 control register 2. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit set in the mask will cause the corresponding bit in the control register to be cleared. + + +HwReadA2Control2 Read Asic2 register 2 + + +None +RETURN: + +AL The value currently in control register 2. +PANIC: None + + +This service can be used to read Asic2 control register 2. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it returns the value in its up-to-date copy. + + +HwWriteA2Control2 Write Asic2 register 2 + + +AL The new value to be written to control register 2. +RETURN: None +PANIC: None + + +This service can be used to write to Asic2 control register 2. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. + + +HwSetA2Control3Bits Set bits Asic2 register 3 + + +AL Mask of bits to be set. +RETURN: None +PANIC: None + + +This service can be used to set bits in Asic2 control register 3. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit set in the mask will cause the corresponding bit in the control register to be set. + + +HwClearA2Control3Bits Clear bits Asic2 register 3 + + +AL Mask of bits to be cleared. +RETURN: None +PANIC: None + + +This service can be used to clear bits in Asic2 control register 3. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Each bit set in the mask will cause the corresponding bit in the control register to be cleared. + + +21-3 + + +EPOC O/S SYSTEM SERVICES + + +HwReadA2Control3 Read Asic2 register 3 + + +None +RETURN: + +AL The value currently in control register 3. +PANIC: None + + +This service can be used to read Asic2 control register 3. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it returns the value in its up-to-date copy. + + +HwWriteA2Control3 Write Asic2 register 3 + + +AL The new value to be written to control register 3. +RETURN: None +PANIC: None + + +This service can be used to write to Asic2 control register 3. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. + + +HwSelectChannel Select a serial channel +AL The new channel to be selected. + +RETURN: +AL The channel that was previously selected. + + +PANIC: None +This service will select which channel the serial controller in Asic2 will be connected to for subsequent +serial data transfers. + + +This service is necessary because the operating system cannot read directly from Asic2 and must keep its +own up-to-date copy of the register contents. + + +Interrupt service routines which use the serial controller must re-select the channel that was previously +selected. This can be achieved by saving the value returned in AL when this service is called, as it is the +currently selected channel. + + +HwNullFrame Send a serial null frame + + +None +RETURN: None +PANIC: None + + +This service is useful for sending a null frame to a serial channel. This is important in order to guarantee +that the controller and the slave device attached to the channel are synchronised. + + +HwSwitchOff Switch off + + +cx The number of quarter seconds to switch off for. +RETURN: None +PANIC: None + + +This service may be called to switch off the machine. In fact, the machine is never truly switched off and +can wake up again in order to service an event in the future. The value in CX determines how many +quarters of a second must pass before the machine will wake up again. If the value in CX is less than or +equal to 8 then this service will do nothing. + + +21-4 + + +21 HARDWARE MANAGEMENT + + +If an absolute timer is pending or a process is sleeping until an absolute time then the value in CX will be +adjusted to make sure that the machine wakes up in time to service the outstanding timer or to wake up +the process. + + +If the value in CX is OxFFFF then the machine will just switch off until an outstanding absolute time +event is ready to expire or until the user switches on the machine. + + +The IBM PC version of EPOC does not support this service; instead, the HwExit service can be called +which will return to DOS. + + +HwExit Exit to DOS + + +None +RETURN: None +PANIC: None + + +This service is only available on the IBM PC version of Epoc/Os and will exit from the operating system +and return to DOS. + + +HwGetCombo Capture the combo subsystem + + +None +RETURN: = Carry clear +Success +RETURN: Carry set +InUseErr The combo subsystem is already captured. +PANIC: None +This service acts as a gate to the combo subsystem so that two device drivers do not both try to access the + + +combo subsystem at the same time. + + +After capturing the combo subsystem, it must be released by calling the Hwrreecombo service when no +longer required + + +HwFreeCombo Free the combo subsystem + + +None +RETURN: None +PANIC: None + + +This service will free the combo subsystem after it has been captured with the HwGet combo service. + + +HwGetChannel Get a channel + + +AL The mask of the channels being captured. +RETURN: Carry clear +Success. +RETURN: = Carry set +InUseErr The channel is already captured. +PANIC: None +This service provides a gate to control access to the hardware interrupt service routines. + + +It is also a handy way of ensuring that two device drivers do not start talking to the same expansion port at +the same time, by getting the channel which is associated with that expansion port. + + +The strategy is to request the channel before trying to talk to the hardware. If the channel is allocated +successfully, then all is well and the driver can then talk to the expansion port. Whenever a driver has +captured a channel in this way it must free the channel when it is no longer required by calling the +HwFreeChannel Service. + + +21-5 + + +EPOC O/S SYSTEM SERVICES + + +HwFreeChannel Free a channel + + +AL The mask of the channels being freed. +RETURN: None +PANIC: None + + +This service will free a channel after it has been captured with the HwGetChannel service. + + +HwGetPsuType Get the power supply type + + +None +RETURN: + +AL The power supply type. +PANIC: None + + +There are two power supply variants in the MC range of computers which use the EPOC operating +system. Consequently there are two version of the operating system due to the different power supply +handling code. Apart from this service, EPOC hides the differences between the two power supplies. The +REPRO software which will load a new operating system into the FLASH memory uses this service to +know which version of EPOC to load. + + +HwGetSupplyStatus Get supplies status + + +SS:BX Pointer to a SupplyEnt structure. +RETURN: None +PANIC: None +This service may be used to get the current status of the various supplies. + + +The value returned for the main battery and lithium batteries are in millivolts. The MainsPresent field +can be: + + +<0 mains status cannot be determined at the current +time (if the SSD doors are open) + + +0 mains is not present +1 mains is present +HwSupplyWarnings Get supplies warnings +SS:BX Pointer to a SupplyWarningsEnt Structure. + + +RETURN: None +PANIC: None + + +This service may be used to ask the operating system what the maximum value of the main and lithium +battery reading can be and what an appropriate warning level would be. The values in the structures are in +the same units as for the HwGet SupplyStatus, 1.e. millivolts. + + +This service will return different values depending on the battery type set with the censetBatteryType +service. If no battery type is set then the values for an alkaline battery will be returned. + + +HwLcdContrastDelta Change the LCD contrast + + +AL +ve to step contrast up. +-ve to step contrast down. +RETURN: None +PANIC: None + + +This service can be used to step the LCD contrast up or down depending on whether AL is positive or +negative. + + +21-6 + + +21 HARDWARE MANAGEMENT + + +HwReadLcdContrast Get current LCD contrast + + +None +RETURN: + +AL The current contrast value. +PANIC: None + + +This service can be used to get the current contrast setting. + + +HwSetBackLight Set backlight control + + +BX The new backlight control value. +RETURN: None +PANIC: None +This service can be used to set the backlight control. + + +The value in BX contains two values. The bottom 15 bits are a time-out in ticks (1/32nd of a second) to +switch off the backlight. If this value is zero then the backlight is not switched off automatically. + + +The top bit (i.e. the sign bit), is used to enable/disable the operating system from toggling the backlight +state on reception of the backlight key. Setting the bit will disable the operating system. + + +HwGetBackLight Get backlight control + + +None +RETURN: + +AX The backlight control value. +PANIC: None + + +This service can be used to get the current backlight control value. + + +HwBackLight Operate the backlight + + +AL 0 - Switch off the backlight. +1 - Switch on the backlight. +2 - Toggle the backlight. +3 - Return the backlight state. +RETURN: Carry clear +AL The previous or current backlight state: +0 - backlight is/was off. +1 - backlight is/was on. +RETURN: Carry set +Not SupportedErr Machine does not support a backlight. +PANIC: None + + +This service can be used to perform the following functions: +e Switch the backlight on and off. +e =6Toggle the backlight state. +e Query the current backlight state. + + +A backlit version of the machine can be determined by checking for the Not supportErr being returned +with AL = 3 to query the backlight state. + + +21-7 + + +EPOC O/S SYSTEM SERVICES + + +©HwGetScanCodes Scan the state of all keys + + +BX Pointer to 10 word array to take the scan codes. +RETURN: Nothing. +PANIC: None + + +Writes values to the array at BX corresponding to the state of each key on the keyboard and to each +application button. A unique bit is set for each key being pressed when this service is called. If the key is +up then no bit is set. + + +On the Series 3a, eleven bits are valid in each of the first eight words and the Workabout uses nine bits in +each of the first eight words. On HC machines, eight bits in ten words are valid. This service is not +available on the MC400, MC200 and Series 3. + + +The set of scan codes is different for each machine's keyboard layout, but is fully determined by the +position of the key on each type of machine. + + +The following diagrams specify the scan code associated with each key on the different machines which +support this service. Each box represents a key. The first number in each box gives the element of the +array at BX used for that key (first element 0), and the second number gives the hexadecimal mask +which, when anped with that array element, gives a non-zero result if that key is down. For example, on a +Series 3a if the Control key is being pressed, element 2 of the array anped with hex 80 is non-zero. + + +Series 3a keyboard + + +HC alphabetic keyboard + + +0,080 6,040 7,040 + + +Note that the scan code (0, 080) given for the On/Off key is that for Off. The scan codes for On +(8,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. + + +21-8 + + +21 HARDWARE MANAGEMENT + + +The Off scan code is received if the application captures the Off key (capture of this key by the HC +Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide) + + +HC numeric keyboard + + +0,080 6,040 7,040 + + +0,020 3,001 3,002 3,004 3,008 0,010 +6,020 1,004 1,008 1,010 5,002 6,002 + + +5,001 0,040 0,004 0,008 +5,010 5,008 5,004 7,002 +0,001 + + +Note that the scan code given for the On/Off key (0, 080) is that for Off. The scan codes for On + +(g,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. +The Off scan code is received if the application captures the Off key (capture of this key by the HC +Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide). + + +Workabout keyboard + + +C= + + +3,040 4,040 5,040] |6,040 oa +6.020 7,020 0,040 1,040 eS +2,020 3,020 4,020 5,020 +6,010 7,010 0,020 1,020 +2,010 3,010 4,010 5,010 +(— +6, 008 7,008 0,010 1,010 +NG +0,00 1,00 2,00 3,00 4,00 5,00 +2,004 3,004 4,004 5,004 6,004 7,004 +4,004 5,002 6, 002 7,002 0,004 1,004 +0,00] 1,004 0,004 1,004 2,002 3,002 +( > +2,001 4,00] 5,00] +S S +(— ay +3,001 6,00] 7,00] +X S + + +21-9 + + +EPOC O/S SYSTEM SERVICES + + +Note that the scan code given for the On/Esc key (0,100) is the Escape scan code. The scan codes for On +(0, 080 - not shown in the above diagram) and Off (6, 020) are not normally received by application code. +The Off scan code is received if the application captures the Off key. + + +©HwComboOninput Switch on the combo in input mode + + +None +RETURN: None +PANIC: None + + +This service is equivalent to HwComboon for all variants except Asic9 variants (Series 3a). On Asic9 +variants HwComboon turns on the codec and puts it into output mode. HwcomboOnInput also turns on the +codec but puts it into input mode. + + +©HwSupplyinfo Get additional power supply data + + +BX Pointer to supplyInfokEnt structure +RETURN: Nothing. +PANIC: None. + + +Write information concerning the various power supplies to the supplyInfokEnt structure at BX. This +information can be used to monitor battery and mains usage. Only Asic9 variants (Series 3a) return +meaningful data. + + +The supplyInfoknt structure is defined in epocsibo.inc. + + +Hardware Management update + + +The majority of the additional EPOC hardware management system services described in this section were +introduced for the Series 3c and Siena. + + +With the exception of the HC, all the services are, in principle, available on any machine that contains +EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in +this section should generate an =_GEN_NsuP error. + + +Some services require the presence of hardware that is not built into all machines in the SIBO range. If +the relevant hardware is not present on a particular machine, calling the service will either have no effect +or return an error of —_GEN_Nnsup. The descriptions of such services contain a list of the machines on +which they are intended to be used. + + +HwResetBatteryStatus Reset the battery status + + +None +RETURN: None +PANIC: None + + +Reset the battery status information. This service has the same effect as replacing the main batteries. + + +HwEnableAutoBatReset Enable/disable battery info reset +BX Enable/disable/query the status + +RETURN: +AL The current auto battery reset status, if queried, otherwise none. + + +PANIC: None + + +This service is primarily intended for use on the Workabout. +Enable or disable an auto reset of the battery information when the battery is recharged in-place. +The value of BX should be 1 to enable, 0 to disable, or -1 to query the auto reset status. + + +If querying the status, a value of lor 0 is returned in AX, respectively meaning that auto reset is enabled +or disabled. + + +21-10 + + +21 HARDWARE MANAGEMENT + + +HwGetBatData Return battery information +None + +RETURN: +AX Pointer to battery information. + + +PANIC: None + + +Return the address of the supplyInfoEnt battery information structure in the OS data segment. +The structure is defined as: + + +SupplyInfoEnt struc + + +SuMainBat Level db ? +SuMainBatStatus db ? +SuBackupBatLevel db ? +SuDcLevel db ? +SuWarningFlags dw ? +SuInsertionDate dd 2 +SuTicksInUseBattery dd ? +SuTicksInUseDc dd ? +SuMilliampTicks dd ? + + +SupplyInfoEnt ends + + +This structure is equivalent to the PLIB &_suppLy_inro struct. + + +HwReLogPacks Relog the SSDs + + +None + + +RETURN: = Carry clear + + +Success +RETURN: = Carry set +AL Error number + + +PANIC: None + + +Relog the packs. This service has the same effect as opening and then closing the pack doors on a +Series 3a. + + +This service is supplied for internal use and is not intended to be called by application code. + + +HwSetiRPowerLevel Set the IR power level +BX Required power level + +RETURN: +AX The previous IR power level + + +PANIC: None + + +This service is only available on Series 3c and Siena machines. +Set the power level used to drive the IR device to be high or low. +BX should be passed as | to set the high power level, or 0 to set the low power level. + + +Return a value (0 for low and 1 for high) representing the IR power level as it was before the service was +called. + + +HwReturnTickCount Sense the current tick count + + +None +RETURN: + +AX Tick count. +PANIC: None + + +Return, in AX, a value that is incremented on every tick (32 times per second). + + +21-11 + + +EPOC O/S SYSTEM SERVICES + + +HwReturnExpansionPortState Sense the expansion port state + + +None + +RETURN: +AX Expansion port state. +BX At present, always zero. + + +PANIC: None + + +Return the type and current state of the expansion port: + + +The value of AL is non-zero if the pack doors are open. Additionally, on Series 3c machines, it is non zero +for a short period after something is plugged into, or removed from, the Honda connector. + + +AH contains one of the following values in its lower three bits: + + +0x00 Expansion port is Series 3/ Series 3a 6-pin +0x01 Expansion port is Workabout LIF + +0x02 Expansion port is Siena Honda + +0x03 Expansion port is Series 3c Honda + +0x04 Expansion port is HC + + +In addition, the following value may be ored into AH: + + +0x80 The machine contains the Condor chip + + +HwExpansionOn Enable power to Honda connector + + +None +RETURN: None +PANIC: None + + +This service is only available on Series 3c machines. +Enable the supply of power to a peripheral device connected to the machine via the Honda connector. + + +This service is provided for the built-in SSD drivers and should not be called by any other drivers or +applications. + + +HwExpansionOff Disable power to Honda connector + + +None +RETURN: None +PANIC: None + + +This service is only available on Series 3c machines. +Disable the supply of power to a peripheral device connected to the machine via the Honda connector. + + +This service is provided for the built-in SSD drivers and should not be called by any other drivers or +applications. + + +21-12 + + +APPENDIX A + + +INTERRUPT AND FUNCTION NUMBERS + + +Introduction + + +Epoc system services are invoked using the INT nn 8086 instruction. There are two types of system +services. + + +e Single - which just do one function. +e = Multi - which do more than one function. + + +The multi service functions also require the AH register to be loaded with a value which selects the actual +function to be performed. + + +The following section lists the actual numbers associated with the system services and their function +numbers. In the listings, names starting with Nm are function numbers and should be placed in AH. All +names starting with Nm are made up of Nm followed by a number of name components. The first +component after Nm is the name of the interrupt to invoke. For example: + + +NmFilOpen, where Fil is the first name component uses FilManager. + + +NmHeapFreeCell, where Heap is the first name component uses HeapManager. NmDbfClose, where Dbf +is the first name component uses DbfManager. + + +MOV AH, NmFilOpen +INT FilManager + + +All names not starting with Nm are the names of the single and multi level interrupts. + + +In the documentation, functions are referred to by the name with the leading Nm missing. Thus SegOpen +can be called as follows: + + +MOV AH, NmSegOpen +INT SegManager + + +Single service interrupts are just referred to by their names. Thus StringLength is called as follows: +INT StringLength +As usual there are a few exceptions to this rule: + + +e NmLongUnsignedIntRandom is under INT GenManager. NmloOpen is under INT DevManager. + + +EPOC O/S SYSTEM SERVICES + + +Alphabetical list of functions + + +CONVMANAGER + + +NMCONVARGUMENTSTOBUFFER + + +NMCONVFLOATTOBUFFER + + +NMCONVINTI + + +TOBUFFER + + +NMCONVLONGINI + + +NMCONVSTRI + + +NMCONVSTRI + + +NMCONVSTRI + + +NMCONVSTRI + + +NMCONVSTRI + + +NMCONVUNSI + + +NG1 + + +NG1 + + +NG1 + + +NG1 + + +[TTOBUFFER + + +TOF LOAT + + +TOINT + + +TOLONGINT + + +TOUNSIGNEDINT + + +NG1 + + +TOUNS IGNEDLONGINT + + +GNEDINTTOBUFFER + + +NMCONVUNSI + + +DBFMANAGER + + +GNEDLONGINTTOBUFFER + + +NMDBFABSREAD + + +NMDBFABSREADSENSE + + +NMDBFAPPEND + + +NMDBFBACKREAD + + +NMDBFCLOSE + + +NMDBFCOMPRESS + + +NMDBFCOP YDOWN + + +NMDBFCOPYFILE + + +NMDBF COUNT + + +NMDBFDESCRECORDREAD + + +NMDBFDESCRECORDWRITE + + +NMDBFERASEREAD + + +NMDBFEXTHEADERREAD + + +NMDBFEXTHEADERWRITE + + +NMDBFFILESIZE + + +NMDBFF INDREAD + + +NMDBFF INDREADFIELD + + +NMDBFFIRSTREAD + + +NMDBFF LUSH + + +NMDBFLASTREAD + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +OO8AH + + +0004H + + +0009H + + +0002H + + +0003H + + +OOOAH + + +0007H + + +0008H + + +0005H + + +OO06H + + +OOOOH + + +0001H + + +OOD8H + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +DBFNEXTREAD + + +DBFOPEN + + +DBFSENSE + + +DBF TRASH + + +DBFUPDATE + + +DBFVERSION + + +DEVMANAGER + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +DEVDELETE + + +DEVF IND + + +DEVGETPDDADDRESS + + +DEVHOLD + + +DEVINSTALL + + +DEVLOADLDD + + +DEVLOADPDD + + +DEVOPENPDD + + +DEVQUERYUNITS + + +DEVREMOVE + + +DEVRESUME + + +DEVVECTOR + + +IOOPEN + + +FILMANAGER + + +NMF ILCHANGEDIRECTORY + + +NMF ILCONNECT + + +NMF ILDELETE + + +NMF ILEXECUTE + + +NMF ILLOCCHANGED + + +NMF ILLOCDEVICE + + +NMF ILLOCREADPDD + + +NMF ILMAKEDIRECTORY + + +NMF ILOPENUNIQUE + + +NMF ILPARSE + + +NMF ILPATHGET + + +NMF ILPATHGETBYID + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +OOODH + + +0000H + + +0015H + + +0003H + + +0013H + + +OOOAH + + +0085H + + +0087H + + +EPOC O/S SYSTEM SERVICES + + +NMF ILPATHSET + + +NMFILPATHTEST + + +NMF I LRENAME + + +NMFILSETFILEDATE + + +NMFILSETINITIALPATH + + +NMFILSTATUSDEVICE + + +NMFILSTATUSGET + + +NMFILSTATUSSET + + +NMFILSTATUSSYSTEM + + +NMFILSYSTEMATTACH + + +NMFILSYSTEMDETACH + + +FLOATMANAGER + + +NMFLOATACOS + + +NMF LOATASIN + + +NMF LOATATAN + + +NMFLOATCOS + + +NMF LOATEXP + + +NMF LOATINT + + +NMF LOATLN + + +NMF LOATLOG + + +NMF LOATMOD + + +NMF LOATPOW + + +NMF LOATRAND + + +NMFLOATSIN + + +NMF LOATSQRT + + +NMF LOATTAN + + +GENMANAGER + + +NMGENALARMHOOK + + +NMGENALARMID + + +NMGENALARMUNHOOK + + +NMGENCRC + + +NMGENDEFERREDMODE + + +NMGENENVBUFFERDELETE + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +0004 + + +0005H + + +0007 + + +0013H + + +0012H + + +OO0A + + +0008 + + +0009H + + +OOOBH + + +OOOE + + +OOOFH + + +008C + + +oO + +fo} + +fo} + +as +r + + +oO + +oO + +oO + +Ww +r + + +fo} + +fo} + +oO + +ray +r + + +Le + +fo} + +oO + +oO) +r + + +fo} + +fo} + +fo} + +~ +r + + +oO + +fo} + +oa + +foo) +r + + +fo) +fo) +fo) +aa +" + + +0O8BH + + +002BH + + +002DH + + +002CH + + +0029H + + +0008H + + +0023H + + +NMGENENVBUFFERF IND + + +NMGENENVBUFFERGET + + +NMGENENVBUFFERSET + + +NMGENENVSTRINGDELETE + + +NMGENENVSTRINGF IND + + +NMGENENVSTRINGGET + + +NMGENENVSTRINGSET + + +NMGENGETAMPMTEXT + + +NMGENGETAUTOMAINS + + +NMGENGETAUTOSWITCHOFF VALUE + + +NMGENGETBATTERYTYPE + + +NMGENGETCOMMANDLINE + + +NMGENGETCOUNTRYDATA + + +NMGENGETERRORTEXT + + +NMGENGETLANGUAGECODE + + +NMGENGETNOTIFYSTATE + + +NMGENGETOSDATA + + +NMGENGETRAMSIZEINPARAS + + +NMGENGETSOUNDFLAGS + + +NMGENGETSUFFIXES + + +NMGENGETTEXT + + +NMGENLCDTYPE + + +NMGENMARKACTIVE + + +NMGENMARKNONACTIVE + + +NMGENMASKDECRYPT + + +NMGENMASKENCRYPT + + +NMGENMASKINIT + + +NMGENNOTIFY + + +NMGENNOTIFYERROR + + +NMGENNOTIFYHOOK + + +NMGENNOTIFYUNHOOK + + +NMGENPARSE + + +NMGENPASSWORDCONTROL + + +NMGENPASSWORDQUERY + + +NMGENPASSWORDSET + + +NMGENPASSWORDTEST + + +NMGENRESETREVECTOR + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +EPOC O/S SYSTEM SERVICES + + +NMGENROMVERS ION + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +NMGENSET + + +TAUTOMAINS + + +TAUTOSWITCHOFF VALUE + + +[TBATTERYTYPE + + +[CONFIG + + +TCOUNTRYDATA + + +[NOTIFYSTATE + + +TONEVENTS + + +TREVECTOR + + +TSOUNDF LAGS + + +NMGENSOUND + + +NMGENSTARTREASON + + +NMGENTICKLE + + +NMGENVERSION + + +NMLONGUNSIGNEDINTRANDOM + + +HEAPMANAGER + + +NMHEAPADJUSTCELLSIZE + + +NMHEAPALLOCATECELL + + +NMHEAPCELLSIZE + + +NMHEAPFREECELL + + +NMHEAPFREEMEMORY + + +NMHEAPREALLOCATECELL + + +NMHEAPSETGRANULARITY + + +HWMANAGER + + +NMHWBACKLIGHT + + +NMHWCLEARA2CONTROLIBITS + + +NMHWCLEARA2CONTROL2BITS + + +NMHWCLEARA2CONTROL3BITS + + +NMHWCOMBOOFF + + +NMHWCOMBOON + + +NMHWCOMBOONINPUT + + +NMHWEXIT + + +NMHWFORCESUPPLYREADING + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +0081 + + +OO8E + + +0020 + + +0005 + + +0009 + + +000D + + +0001 + + +0000 + + +0021 + + +0016 + + +001D + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +H + + +WFREECHANNEL + + +WFREECOMBO + + +WGETBACKLIGHT + + +WGETCHANNEL + + +WGETCOMBO + + +WGETPSUTYPE + + +WGETSCANCODES + + +WGETSUPPLYSTATUS + + +WLCDCONTRASTDELTA + + +WNULLFRAME + + +WPACKSOFF + + +WPACKSON + + +WREADA2CONTROL1 + + +WREADA2CONTROL2 + + +WREADA2CONTROL3 + + +WREADLCDCONTRAST + + +WSELECTCHANNEL + + +WSETA2CONTROLIBITS + + +WSETA2CONTROL2BITS + + +WSETA2CONTROL3BITS + + +WSETBACKLIGHT + + +WSUPPLYINFO + + +WSUPPLYWARNINGS + + +WSWITCHOFF + + +WWRITEA2CONTROL1 + + +WWRITEA2CONTROL2 + + +WWRITEA2CONTROL3 + + +IOMANAGER + + +NM] + + +NM] + + +NM + + +NM] + + +NMI + + +NM + + +NMI + + +OADDAPPLICATIONHANDLER + + +OADDHANDLER + + +IOASYNCHRONOUS + + +OASYNCHRONOUSNOERROR + + +OCLOSE + + +IOENABLEAPPLICATIONHANDLER + + +OENABLEHANDLER + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +OO1A + + +0018 + + +0086 + + +0015 + + +000B + + +0000 + + +0001 + + +0010 + + +0017 + + +000D + + +EPOC O/S SYSTEM SERVICES + + +NMI + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NMI] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +OKEYANDMO + + +OKEYANDMO + + +ONEXTHALF + + +OPLAYSOUN + + +OPLAYSOUN + + +OPLAYSOUN + + +OREAD + + +ORECORDSO + + +ORECORDSO + + +ORECORDSO + + +OREMOVEAPPLICATIONHANDLER + + +USEASYNCHRONOUS + + +USEWITHWAIT + + +SECOND + + +DA + + +DCANCEL + + +DW + + +UNDA + + +UNDCANCEL + + +UNDW + + +OREMOVEHANDLER + + +OREQUESTRESET + + +OREQUESTRESETCANCEL + + +OROOT + + +OSEEK + + +OSHIFTSTATES + + +OSIGNAL + + +OSIGNALBYPID + + +OSIGNALBYP IDNORESCHED + + +OSIGNALKILLASYNCHRONOUS + + +OSIGNALKILLCANCEL + + +OSUPER + + +OWAITFORS + + +OWAITFORS + + +IGNAL + + +IGNALNOHANDLER + + +OWAITFORSTATUS + + +OWITHWAIT + + +OWRITE + + +OYIELD + + +IOSERMANAGER + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +OSERADDHANDLER + + +OSERATTACHONOPENCHAN + + +OSERCANCELALLSIGNALUSER + + +OSERCANCELIOREQUEST + + +OSERCHECKREADSI + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +001C + + +0014 + + +OODE + + +0001 + + +0O00D + + +0O01C + + +001B + + +0011 + + +NM] + + +NM] + + +NM + + +NM] + + +NM] + + +NM + + +NM] + + +NM] + + +NM + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +OSERCHECKWRITESI + + +OSERCLOSETIMERHANDLER + + +IOSERDETACHFREE + + +OSERFREE + + +OSERHANDLERSAVEERROR + + +IOSERONOPENCHAN + + +OSEROPEN + + +OSEROPENHANDLER + + +IOSEROPENT IMERHANDLER + + +OSERQUEUEREAD + + +OSERQUEUESUPER + + +OSERQUEUETIMER + + +OSERQUEUEWRITE + + +OSERREMOVEHANDLER + + +OSERSENSEONOPENCHAN + + +OSERSETHANDLER + + +OSERSIGNALCOMPLETE + + +OSERS IGNALCOMP LETEOK + + +OSERSIGNALUSER + + +OSERS IGNALUSERREAD + + +OSERS IGNALUSERREADOK + + +OSERSIGNALUSERWRITE + + +OSERSIGNALUSERWRITEOK + + +OSERSYNCWRITE + + +OSERTIMERCANCEL + + +OSERTIMERCLOSE + + +OSERTIMEROPEN + + +LIBMANAGER + + +NMLI + + +NMLI + + +NMLI + + +NMLI + + +BCOPY + + +BCREATE + + +IBCREATEBYHANDLE + + +IBDESTROY + + +IBFIND + + +BHANDLE + + +BLINK + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +0084 + + +0008 + + +0005 + + +0006 + + +0007 + + +0003 + + +0004 + + +0002 + + +EPOC O/S SYSTEM SERVICES + + +NMLIBLOAD EQU OOOOH +NMLIBLOADFILE EQU OOOAH +NMLIBOPEN EQU 0009H +NMLIBRECLASS EQU OOOBH +NMLIBRECLASSBYHANDLE EQU OOOCH +NMLIBUNLOAD EQU 0001H +MES SMANAGER EQU 0083H +NMMESSFREE EQU 0007H +NMMESSINIT EQU OOOOH +NMMESSRECEIVEAS YNCHRONOUS EQU 0001H +NMMESSRECEIVECANCEL EQU 0003H +NMMESSRECEIVEWITHWAIT EQU 0002H +NMMESSSEND EQU 0004H +NMMESSSENDRECEIVEAS YNCHRONOUS EQU 0005H +NMMESSSENDRECEIVEWITHWAIT EQU OO006H +NMMESSSIGNAL EQU 0008H +NMMESSSIGNALCANCEL EQU 0009H +NMMESSSIGNALCANCELX EQU OOOAH +PROCMANAGER EQU 0088H +NMP ROCCREATE EQU 0004H +NMPROCCREATETASK EQU 0005H +NMPROCF IND EQU OOOBH +NMP ROCGETOWNER EQU 0010H +NMPROCGETPRIORITY EQU 0002H +NMPROCID EQU OOOOH +NMPROCIDBYNAME EQU 0001H +NMPROCKILL EQU 0008H +NMP ROCNAMEBY ID EQU OOOAH +NMPROCONTERMINATE EQU OOOEH +NMPROCPANICBYID EQU 0009H +NMP ROCRENAME EQU OOOCH +NMP ROCRESUME EQU OO006H +NMPROCSETPRIORITY EQU 0003H + + +A-10 + + +A INTERRUPT AND FUNCTION NUMBERS + + +NMP ROCSUSPEND EQU OOO07H +NMPROCTERMINATE EQU OOODH +NMPROCWATCHALLEXITS EQU OOOFH +SEGMANAGER EQU 0080H +NMSEGADJUSTSIZE EQU OO006H +NMSEGCLOSE EQU 0004H +NMSEGCLOSELOCKEDORDEVICE EQU OOODH +NMSEGCOP YFROM EQU 0009H +NMSEGCOPYTO EQU 0008H +NMSEGCREATE EQU 0001H +NMSEGDELETE EQU 0002H +NMSEGF IND EQU OO007H +NMSEGFREEMEMORY EQU OOOOH +NMSEGLOCK EQU OOOAH +NMSEGOPEN EQU 0003H +NMSEGRAMDISKUSED EQU OOOCH +NMSEGSIZE EQU 0005H +NMSEGUNLOCK EQU OOOBH +SEMMANAGER EQU 0082H +NMSEMCREATE EQU OO00H +NMSEMDELETE EQU 0001H +NMSEMS IGNALMANY EQU 0004H +NMSEMSIGNALONCE EQU 0003H +NMSEMS IGNALONCENORESCHED EQU 0005H +NMSEMWAIT EQU 0002H +TIMMANAGER EQU 0089H +NMTIMDATETODAYSECONDS EQU 0007H +NMT IMDAYOFWEEK EQU 0009H +NMTIMDAYSECONDSTODATE EQU OO06H +NMTIMDAYSECONDSTOSYSTEMTIME EQU 0005H +NMTIMDAYSINMONTH EQU 0008H + + +EPOC O/S SYSTEM SERVICES + + +w + + +w + + +w + + +w + + +w + + +w + + +NMTIMGETSYSTEMTIME + + +NMT IMNAMEOFDAY + + +NMT IMNAMEOFDAYABB + + +NMT IMNAMEOFMONTH + + +NMT IMNAMEOFMONTHABB + + +NMTIMSETSYSTEMTIME + + +NMTIMSLEEPFORTENTHS + + +NMTIMSLEEPFORTICKS + + +NMTIMSYSTEMT IMETODAY SECONDS + + +NMTIMWAITABSOLUTE + + +NMT IMWEEKNUMBER + + +UFFERCOMPARE + + +UFFERCOMPAREFOLDED + + +UFFERCOPY + + +UFFERJUSTIFY + + +UFFERLOCATE + + +UFFERLOCATEFOLDED + + +UFFERMATCH + + +UFFERMATCHFOLDED + + +UFFERSUBBUFFER + + +UFFERSUBBUFFERFOLDED + + +UFFERSWAP + + +HARISALPHABETIC + + +HARISALPHANUMERIC + + +HARISCONTROL + + +HARISDIGIT + + +HARISGRAPHIC + + +HARISHEXDIGIT + + +HARISLOWERCASE + + +HARISPRINTABLE + + +HARISPUNCTUATION + + +HARISSPACE + + +HARISUPPERCASE + + +HARTOFOLDEDCHAR + + +HARTOLOWERCHAR + + +HARTOUPPERCHAR + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +DUMMY + + +F LOATADD + + +F LOATCOMPARE + + +FLOATDIVIDE + + +FLOATMULTIPLY + + +FLOATNEGATE + + +FLOATSUBTRACT + + +FLOATTOINT + + +F LOATTOLONG + + +FLOATTOUNSIGNEDINT + + +F LOATTOUNS IGNEDLONG + + +GENDATASEGMENT + + +GENINTBYNUMBER + + +NTTOFLOAT + + +OKEYANDMOUSESTATUS + + +ONEXTHALFSECONDSTATUS + + +LIBENTER + + +LIBENTERSEND + + +LIBLEAVE + + +LIBSEND + + +LIBSENDEXACT + + +LIBSENDEXIT + + +LIBSENDSUPER + + +LONGINTCOMPARE + + +LONGINTDIVIDE + + +LONGINTMULTIPLY + + +LONGTOF LOAT + + +LONGUNS IGNEDINTCOMPARE + + +LONGUNSIGNEDINTDIVIDE + + +LONGUNSIGNEDINTMULTIPLY + + +PROCCOPYFROMBYID + + +PROCCOPYTOBYID + + +PROCINDSTRINGCOPYFROMBYID + + +PROCPANIC + + +STRINGCAPITALISE + + +STRINGCOMPARE + + +STRINGCOMPAREFOLDED + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +OOCFH + + +OOBBH + + +OOBDH + + +OOBCH + + +OOCDH + + +OOBEH + + +OOCOH + + +OOBFH + + +0091H + + +0092H + + +OODCH + + +0090H + + +OODBH + + +OOAFH + + +OOBOH + + +EPOC O/S SYSTEM SERVICES + + +STRINGCONVERTTOFOLDED + + +STRINGCOPY + + +STRINGCOPYFOLDED + + +STRINGLENGTH + + +STRINGLOCATE + + +STRINGLOCATEFOLDED + + +STRINGLOCATEINREVERSE + + +STRINGLOCATEINREVERSEFOLDED + + +STRINGMATCH + + +STRINGMATCHFOLDED + + +STRINGSUBSTRING EQU + + +STRINGSUBSTRINGFOLDED + + +STRINGVALIDATENAME + + +UNSIGNEDINTTOFLOAT + + +UNSIGNEDLONGTOFLOAT + + +WSERVFUNCTIONS EQU + + +WSERVOPCODES + + +Numerical list of functions + + +SEGMANAGER + + +NMSEGFREEMEMORY +NMSEGCREATE +NMSEGDELETE +NMSEGOPEN +NMSEGCLOSE +NMSEGSIZE +NMSEGADJUSTSIZE +NMSEGF IND +NMSEGCOPYTO +NMSEGCOP YFROM +NMSEGLOCK +NMSEGUNLOCK +NMSEGRAMDISKUSED + + +NMSEGCLOSELOCKEDORDEVICE + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +D6H + + +OOAEH + + +OOACH + + +OOADH + + +OOB9H + + +00B3H + + +OOB4H + + +OOB5H + + +OOB6H + + +0OB1H + + +OOB2H + + +OOB8H + + +OOBAH + + +OOCCH + + +OOCEH + + +008DH + + +0080H + + +0000H + + +0001H + + +0002H + + +0003H + + +0004H + + +0005H + + +OO06H + + +OO0O07H + + +0008H + + +0009H + + +OOOAH + + +OOOBH + + +OOOCH + + +OOODH + + +A INTERRUPT AND FUNCTION NUMBERS + + +HEAPMANAGER EQU 0081H +NMHEAPALLOCATECELL EQU OOOOH +NMHEAPREALLOCATECELL EQU 0001H +NMHEAPADJUSTCELLSIZE EQU 0002H +NMHEAPFREECELL EQU 0003H +NMHEAPCELLSIZE EQU 0004H +NMHEAPSETGRANULARITY EQU 0005H +NMHEAPFREEMEMORY EQU OO06H + +SEMMANAGER EQU 0082H +NMSEMCREATE EQU OOOOH +NMSEMDELETE EQU 0001H +NMSEMWAIT EQU 0002H +NMSEMS IGNALONCE EQU 0003H +NMSEMS IGNALMANY EQU 0004H +NMSEMS IGNALONCENORESCHED EQU 0005H + +MES SMANAGER EQU 0083H +NMMESSINIT EQU OOOOH +NMMESSRECEIVEASYNCHRONOUS EQU 0001H +NMMESSRECEIVEWITHWAIT EQU 0002H +NMMESSRECEIVECANCEL EQU 0003H +NMMESSSEND EQU 0004H +NMMESSSENDRECEIVEASYNCHRONOUS EQU 0005H +NMMESSSENDRECEIVEWITHWAIT EQU OO06H +NMMESSFREE EQU 0007H +NMMESSSIGNAL EQU 0008H +NMMESSSIGNALCANCEL EQU 0009H +NMMESSSIGNALCANCELX EQU OOOAH + +LIBMANAGER EQU 0084H +NMLIBLOAD EQU 0O00H +NMLIBUNLOAD EQU 0001H + + +EPOC O/S SYSTEM SERVICES + + +NMLIBLINK + + +NMLIBF IND + + +NMLIBHANDLE + + +NMLIBCREATE + + +NMLIBCREATEBYHANDLE + + +NMLIBDESTROY + + +NMLIBCOPY + + +NMLIBOPEN + + +NMLIBLOADFILE + + +NMLIBRECLASS + + +NMLIBRECLASSBYHANDLE + + +DEVMANAGER + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +IOOPEN + + +DEVOPENPDD + + +DEVGETPDDADDRESS + + +DEVINSTALL + + +DEVHOLD + + +DEVRESUME + + +DEVLOADLDD + + +DEVLOADPDD + + +DEVDELETE + + +DEVQUERYUNITS + + +DEVF IND + + +DEVREMOVE + + +DEVVECTOR + + +IOMANAGER + + +NM] + + +NM] + + +NM + + +NM] + + +NM] + + +NM + + +NMI + + +A- 16 + + +OASYNCHRONOUS + + +OASYNCHRONOUSNOERROR + + +IOWITHWAIT + + +OROOT + + +OSUPER + + +IOWAITFORSIGNAL + + +OWAITFORSTATUS + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +0085H + + +OO000H + + +0001H + + +0002H + + +0003 + + +0004 + + +0005H + + +0006 + + +0007 + + +0008H + + +0009 + + +OO0A + + +OOOBH + + +000C + + +0086H + + +0000 + + +0001H + + +0002H + + +0003 + + +0004H + + +0005 + + +0006 + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NMI + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +NM] + + +OYIELD + + +OSIGNAL + + +OSIGNALBYPID + + +OSIGNALBYP IDNORESCHED + + +OADDHANDLER + + +OREMOVEHANDLER + + +OENABLEHANDLER + + +OREQUESTRESET + + +OREQUESTRESETCANCEL + + +OCLOSE + + +OREAD + + +OWRITE + + +OSEEK + + +OKEYANDMOUSEWITHWAIT + + +OADDAPPLICATIONHANDLER + + +OREMOVEAPPLICATIONHANDLER + + +OENABLEAPPLICATIONHANDLER + + +OSHIFTSTATES + + +OWAITFORS IGNALNOHANDLER + + +OSIGNALKILLASYNCHRONOUS + + +OSIGNALKILLCANCEL + + +OKEYANDMOUSEAS YNCHRONOUS + + +ONEXTHALF SECOND + + +OPLAYSOUNDA + + +OPLAYSOUNDW + + +OPLAYSOUNDCANCEL + + +ORECORDSOUNDA + + +ORECORDSOUNDW + + +ORECORDSOUNDCANCEL + + +FILMANAGER + + +NMF ILCONNECT + + +NMF ILEXECUTE + + +NMF ILPARSE + + +NMF ILPATHGET + + +NMF ILPATHSET + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +0087 + + +0000 + + +0001 + + +0002 + + +0003 + + +0004 + + +EPOC O/S SYSTEM SERVICES + + +NMFILPATHTEST EQU 0005H +NMF ILDELETE EQU OO006H +NMF I LRENAME EQU O007H +NMFILSTATUSGET EQU 0008H +NMFILSTATUSSET EQU 0009H +NMFILSTATUSDEVICE EQU OOOAH +NMFILSTATUSSYSTEM EQU OOOBH +NMF ILMAKEDIRECTORY EQU OOOCH +NMF ILOPENUNIQUE EQU OOODH +NMFILSYSTEMATTACH EQU OOOEH +NMFILSYSTEMDETACH EQU OOOFH +NMF ILPATHGETBYID EQU 0010H +NMF ILCHANGEDIRECTORY EQU 0011H +NMFILSETINITIALPATH EQU 0012H +NMFILSETFILEDATE EQU 0013H +NMF I LLOCCHANGED EQU 0014H +NMF ILLOCDEVICE EQU 0015H +NMF ILLOCREADPDD EQU 0016H +PROCMANAGER EQU 0088H +NMPROCID EQU 0O000H +NMPROCIDBYNAME EQU 0001H +NMPROCGETPRIORITY EQU 0002H +NMPROCSETPRIORITY EQU 0003H +NMP ROCCREATE EQU 0004H +NMP ROCCREATETASK EQU 0005H +NMP ROCRESUME EQU OO06H +NMP ROCSUSPEND EQU OO007H +NMPROCKILL EQU 0008H +NMPROCPANICBYID EQU 0009H +NMP ROCNAMEBY ID EQU OOOAH +NMPROCF IND EQU OOOBH +NMP ROCRENAME EQU OOOCH +NMPROCTERMINATE EQU OOODH +NMPROCONTERMINATE EQU OOOEH +NMPROCWATCHALLEXITS EQU OOOFH +NMP ROCGETOWNER EQU 0010H + + +A-18 + + +TIMMANAGER + + +NMTIMSLEEPFORTENTHS + + +NMTIMSLEEPFORTICKS + + +NMTIMGETSYSTEMT IME + + +NMTIMSETSYSTEMTIME + + +NMTIMSYSTEMT IMETODAY SECONDS + + +NMTIMDAYSECONDS1 + + +NMTIMDAYSECONDS1 + + +TOSYSTEMTIME + + +TODATE + + +NMTIMDATETODAYSECONDS + + +NMTIMDAYSINMONTH + + +NMT IMDAYOFWEEK + + +NMT IMNAMEOFDAY + + +NMT IMNAMEOFMONTH + + +NMTIMWAITABSOLUTE + + +NMT IMWEEKNUMBER + + +NMT IMNAMEOFDAYABB + + +NMT IMNAMEOFMONTHABB + + +CONVMANAGER + + +NMCONVUNSIGNEDINTTOBUFFER + + +NMCONVUNSIGNEDLONGINTTOBUFFER + + +NMCONVINTTOBUFFER + + +NMCONVLONGINTTOBUFFER + + +NMCONVARGUMENTSTOBUFFER + + +NMCONVSTRINGTOUNSIGNEDINT + + +NMCONVSTRINGTOUNS IGNEDLONGINT + + +NMCONVSTRINGTOINT + + +NMCONVSTRINGTOLONGINT + + +NMCONVFLOATTOBUFFER + + +NMCONVSTRINGTOFLOAT + + +GENMANAGER + + +NMGENVERSION + + +NMGENLCDTYPE + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +0089H + + +0O000H + + +0001H + + +0002H + + +0003H + + +0004H + + +0005H + + +0006H + + +OO007H + + +0008H + + +0009H + + +OOOAH + + +OOOBH + + +O0O00CH + + +OOODH + + +OOOEH + + +OOOFH + + +OO8AH + + +OO8BH + + +0O000H + + +0001H + + +EPOC O/S SYSTEM SERVICES + + +NMGENSTARTREASON + + +NMGENPARSE + + +NMLONGUNSIGNEDINTRANDOM + + +NMGENGETCOUNTRYDATA + + +NMGENGETERRORTEXT + + +NMGENGETOSDATA + + +NMGENDEFERREDMODE + + +NMGENNOTIFY + + +NMGENNOTIFYERROR + + +NMGENNOTIFYHOOK + + +NMGENNOTIFYUNHOOK + + +NMGENGETRAMSIZEINPARAS + + +NMGENGETCOMMANDLINE + + +NMGENGETSOUNDFLAGS + + +NMGENSETSOUNDFLAGS + + +NMGENSOUND + + +NMGENMARKACTIVE + + +NMGENMARKNONACT!I + + +NMGENGETTEXT + + +NMGENGETNOTIFYS1 + + +NMGENSETNOTIFYS1 + + +NMGENGETAUTOSWIT + + +NMGENSETAUTOSWIT + + +NMGENSETREVECTOR + + +VE + + +TATE + + +TATE + + +[CHOFF VALUE + + +[CHOFF VALUE + + +NMGENRESETREVEC1 + + +TOR + + +NMGENGETLANGUAGECODE + + +NMGENGETSUFFIXES + + +NMGENGETAMPMTEXT + + +NMGENSETCOUNTRYDATA + + +NMGENGETBATTERYTYPE + + +NMGENSETBATTERYTYPE + + +NMGENENVBUFFERGET + + +NMGENENVBUFFERSET + + +NMGENENVBUFFERDELETE + + +NMGENENVBUFFERF IND + + +NMGENENVSTRINGGET + + +NMGENENVSTRINGSET + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +NMGENENVSTRINGDELETE EQU 0027H +NMGENENVSTRINGF IND EQU 0028H +NMGENCRC EQU 0029H +NMGENROMVERS ION EQU O002AH +NMGENALARMHOOK EQU 002BH +NMGENALARMUNHOOK EQU 002CH +NMGENALARMID EQU 002DH +NMGENPASSWORDSET EQU 002EH +NMGENPASSWORDTEST EQU O002FH +NMGENPASSWORDCONTROL EQU 0030H +NMGENPASSWORDQUERY EQU 0031H +NMGENTICKLE EQU 0032H +NMGENSETCONFIG EQU 0033H +NMGENMASKINIT EQU 0034H +NMGENMASKENCRYPT EQU 0035H +NMGENMASKDECRYPT EQU 0036H +NMGENSETONEVENTS EQU 0037H +NMGENGETAUTOMAINS EQU 0038H +NMGENSETAUTOMAINS EQU 0039H +FLOATMANAGER EQU 008CH +NMFLOATSIN EQU OO00H +NMF LOATCOS EQU 0001H +NMF LOATTAN EQU 0002H +NMF LOATASIN EQU 0003H +NMF LOATACOS EQU 0004H +NMF LOATATAN EQU 0005H +NMF LOATEXP EQU OO06H +NMF LOATLN EQU 0O007H +NMF LOATLOG EQU 0008H +NMF LOATSQRT EQU 0009H +NMF LOATPOW EQU OOOAH +NMF LOATRAND EQU OOOBH +NMF LOATMOD EQU OOOCH +NMF LOATINT EQU OOODH + + +EPOC O/S SYSTEM SERVICES + + +WSERVOPCODES + + +HWMANAGER + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +NMH + + +WCOMBOON + + +WCOMBOOFF + + +WPACKSON + + +WPACKSOFF + + +WSETA2CONTROLIBITS + + +WCLEARA2CONTROLIBITS + + +WREADA2CONTROL1 + + +WWRITEA2CONTROLI + + +WSETA2CONTROL2BITS + + +WCLEARA2CONTROL2BITS + + +WREADA2CONTROL2 + + +WWRITEA2CONTROL2 + + +WSETA2CONTROL3BITS + + +WCLEARA2CONTROL3BITS + + +WREADA2CONTROL3 + + +WWRITEA2CONTROL3 + + +WSELECTCHANNEL + + +WGETSUPPLYSTATUS + + +WLCDCONTRASTDELTA + + +WREADLCDCONTRAST + + +WSWITCHOFF + + +WNULLFRAME + + +WEXIT + + +WGETCOMBO + + +WFREECOMBO + + +WGETCHANNEL + + +WFREECHANNEL + + +WGETPSUTYPE + + +WSUPPLYWARNINGS + + +WFORCESUPPLYREADING + + +WGETBACKLIGHT + + +WSETBACKLIGHT + + +WBACKLIGHT + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +008D + + +OO8E + + +001D + + +OO1E + + +OO1F + + +NMHWCOMBOONINPUT + + +NMHWSUPPLYINFO + + +NMHWGETSCANCODES + + +GENDATASEGMENT + + +PROCPANIC + + +PROCCOPYFROMBYID + + +PROCCOPYTOBYID + + +CHARISDIGIT + + +CHARISHEXDIGIT + + +CHARISPRINTABLE + + +CHARISALPHABETIC + + +CHARISALPHANUMERIC + + +CHARISUPPERCASE + + +CHARISLOWERCASE + + +CHARISSPACE + + +CHARISPUNCTUATION + + +CHARISGRAPHIC + + +CHARISCONTROL + + +CHARTOUPPERCHAR + + +CHARTOLOWERCHAR + + +CHARTOFOLDEDCHAR + + +BUFFERCOPY + + +BUFFERSWAP + + +BUFFERCOMPARE + + +BUFFERCOMPAREFOLDED + + +BUFFERMATCH + + +BUFFERMATCHFOLDED + + +BUFFERLOCATE + + +BUFFERLOCATEFOLDED + + +BUFFERSUBBUFFER + + +w + + +UFFERSUBBUFFERFOLDED + + +w + + +UFFERJUSTIFY + + +STRINGCOPY + + +STRINGCOPYFOLDED + + +STRINGCONVERTTOFOLDED + + +STRINGCOMPARE + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +0021H + + +0022H + + +EPOC O/S SYSTEM SERVICES + + +STRINGCOMPAREFOLDED + + +STRINGMATCH + + +STRINGMATCHFOLDED + + +STRINGLOCATE + + +STRINGLOCATEFOLDED + + +STRINGLOCATEINREVERSE + + +STRINGLOCATEINREVERSEFOLDED + + +STRINGSUBSTRING + + +STRINGSUBSTRINGFOLDED + + +STRINGLENGTH + + +STRINGVALIDATENAME + + +LONGINTCOMPARE + + +LONGINTMULTIPLY + + +LONGINTDIVIDE + + +LONGUNS IGNEDINTCOMPARE + + +LONGUNSIGNEDINTMULTIPLY + + +LONGUNSIGNEDINTDIVIDE + + +F LOATADD + + +7] + + +LOATSUBTRACT + + +7] + + +LOATMULTIPLY + + +7] + + +LOATDIVIDE + + +7] + + +LOATCOMPARE + + +7] + + +LOATNEGATE + + +7] + + +LOATTOINT + + +7] + + +LOATTOUNSIGNEDINT + + +7] + + +LOATTOLONG + + +7] + + +LOATTOUNS IGNEDLONG + + +NTTOFLOAT + + +UNS IGNEDINTTOFLOAT + + +LONGTOF LOAT + + +UNS IGNEDLONGTOFLOAT + + +LIBSEND + + +LIBSENDSUPER + + +LIBSENDEXACT + + +LIBENTER + + +LIBLEAVE + + +DUMMY + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +fo} + +fo} + +Q + +ws +I + + +fo} + +oO + +a + +ol +r + + +oO + +oO + +a + +~ +r + + +fo) +(>) +Q +aa +I + + +fo} + +fo} + +Q + +iw) +i + + +OOCFH + + +GENINTBYNUMBER + + +WSERVFUNCTIONS + + +LIBSENDEXIT + + +DBFMANAGER + + +NMDBFOPEN + + +NMDBFCLOSE + + +NMDBFF LUSH + + +NMDBF TRASH + + +NMDBFCOP YDOWN + + +NMDBFCOMPRESS + + +NMDBFCOPYFILE + + +NMDBFFILESIZE + + +NMDBFEXTHEADERREAD + + +NMDBFEXTHEADERWRITE + + +NMDBFVERSION + + +NMDBFABSREADSENSE + + +NMDBFABSREAD + + +NMDBFNEXTREAD + + +NMDBFBACKREAD + + +NMDBFFIRSTREAD + + +NMDBFLASTREAD + + +NMDBFAPPEND + + +NMDBFERASEREAD + + +NMDBFUPDATE + + +NMDBFF INDREAD + + +NMDBF SENSE + + +NMDBF COUNT + + +NMDBFDESCRECORDREAD + + +NMDBFDESCRECORDWRITE + + +NMDBFF INDREADFIELD + + +LIBENTERSEND + + +IOKEYANDMOUSESTATUS + + +STRINGCAPITALISE + + +PROCINDSTRINGCOPYFROMBYID + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +A INTERRUPT AND FUNCTION NUMBERS + + +0OD5 + + +0O0D6 + + +OOD7 + + +00D8 + + +EPOC O/S SYSTEM SERVICES + + +IONEXTHALFSECONDSTATUS + + +IOSERMANAGER + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +NM + + +OSEROPEN + + +OSERADDHANDLER + + +OSERREMOVEHANDLER + + +OSERSETHANDLER + + +OSERHANDLERSAVEERROR + + +OSEROPENHANDLER + + +OSEROPENT IMERHANDLER + + +OSERFREE + + +OSERCLOSETIMERHANDLER + + +OSERDETACHFREE + + +OSERTIMEROPEN + + +OSERTIMERCANCEL + + +OSERTIMERCLOSE + + +OSERATTACHONOPENCHAN + + +OSERSENSEONOPENCHAN + + +OSERONOPENCHAN + + +OSERCHECKWRITESI + + +OSERCHECKREADSTI + + +OSERS IGNALUSERWRITEOK + + +OSERSIGNALUSERWRITE + + +OSERS IGNALUSERREADOK + + +OSERS IGNALUSERREAD + + +OSERS IGNALUSER + + +OSERQUEUEREAD + + +OSERQUEUEWRITE + + +OSERQUEUESUPER + + +OSERQUEUETIMER + + +OSERCANCELIOREQUEST + + +OSERCANCELALLSIGNALUSER + + +OSERS IGNALCOMP LETEOK + + +OSERSIGNALCOMPLETE + + +OSERSYNCWRITE + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +OODD + + +OODE + + +Additional Interrupt and Function numbers + + +A INTERRUPT AND FUNCTION NUMBERS + + +The majority of the additional EPOC system services functions described in this section were introduced + + +for the Series 3c and Siena. + + +With the exception of the HC, all the services are, in principle, available on any machine that contains +EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in + + +this section should generate an =E_GEN_NsuP error. + + +Some services require the presence of hardware that is not built into all machines in the SIBO range. If +the relevant hardware is not present on a particular machine, calling the service will either have no effect + + +or return an error of E_GEN_NSUP. + + +Alphabetical list of extra functions + + +HWMANAGER + + +NMHWENABLEAUTOBATRESET +NMHWEXPANSIONOFF +NMHWEXPANSIONON +NMHWGETBATDATA +NMHWRELOGPACKS +NMHWRESETBATTERYSTATUS +NMHWRETURNEXPANS IONPORTSTATE +NMHWRETURNTICKCOUNT +NMHWSETIRPOWERLEVEL + + +IOMANAGER + + +NMIOPLAYSOUNDAO + + +Numerical list of extra functions + + +IOMANAGER + + +NMIOPLAYSOUNDAO + + +HWMANAGER + + +NMHWRESETBATTERYSTATUS +NMHWENABLEAUTOBATRESET +NMHWGETBATDATA +NMHWRELOGPACKS +NMHWSETIRPOWERLEVEL +NMHWRETURNTICKCOUNT +NMHWRETURNEXPANSIONPORTSTATE +NMHWEXPANSIONON +NMHWEXPANSIONOFF + + +EQ + + +EQ +EQ +EQ +EQ +EQ +EQ +EQ +EQ +EQ + + +EQ + + +EQ + + +EQ + + +EQ + + +aq + + +GaGQaGQGGaGaaGAaaGG + + +GaGa aqqaqaaaqaaG + + +OO8EH + + +002bH +0033H +0032H +002cH +002eH +002aH +0031H +0030H +O02fH + + +0086H + + +0024H + + +0086H + + +0024H + + +008EH + + +002aH +002bH +002cH +002eH +OO2fH +0030H +0031H +0032H + + +0033H + + +APPENDIX B + + +ENVIRONMENT VARIABLES + + +This document is a beta version and is subject to change. + + +This chapter documents all environment variables that, at the time of writing, are created or read by +Psion’s software running on SIBO machines. Note that the names of all such environment variables +contain the ‘$’ character. + + +Environment variables survive a soft reset but are cleared on a hard reset. Some environment variables +will be restored to their default values, by being loaded from a ROM initialisation file, on a hard reset. +The set of environment variables that are restored in this way depends on both the machine type and the +machine’s localisation (language). + + +PLIB + + +EM$ + + +This environment variable is used by the CLIB and PLIB startup modules. It contains a string that +specifies a search path for the 8087 emulator, sys$8087. Idd. + + +Window server +$WS_FL + + +On an HC with version 3.5 of the window server, and in all machines that use version 4 or later, the +initial value of the internal parameter that is set by wsystem is loaded from the sws_FL environment +variable when the window server starts. + + +After setting sws_r1 to the desired worp value, you must reset the HC by pressing the recessed reset button +to make the new value effective. + + +The wsystem flags parameter is made up by oring a number of bit fields of the form wsERV_FLAG_Xxx. + + +After a hard reset on an HC with version 3.5 of the window server, the sws_FL environment variable does +not exist (which is equivalent to it being zero). + + +The following example program sets the sws_FL environment variable: + + +#include +#include + + +GLDEF_C INT main(VOID) +{ +WORD flags; + + +flags=WSERV_FLAG_NO_NOTIFIER_REBOOT |WSERV_FLAG_HOOK_NOTIFIER +| WSERV, FLAG LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW; + +return (p_setenviron("SWS_FL",6,&flags,2))j; + +} + + +EPOC O/S SYSTEM SERVICES + + +After running this program and resetting the HC, the window server will: +e provide the notifier service +e report low battery voltages +e present a hung-up status window if an application hangs + + +e report a process that terminates with a panic or with a negative reason number + + +$WS_FNTS + + +This environment variable contains a series of words, each of which contains the index of a font used by +the window server. The fonts are as follows: + + +e System font + +e §=6Notifier/Alert font + +e §=©Status Window font + +e Symbols font used for the status window diamond symbol +e Medium 2 digital clock font + +e Medium 2 date font + +e =©Notifier/alert button font + + +e Small status window clock font + + +$WS_IF + + +On the HC, the font used for output that is not graphics context directed is determined by the sws_1F +("Internal Font") environment variable. + + +This should contain a worp binary value of 0 for ws_ront_Base, | for ws_FoNT_BASE+1, and so on. If you +change the value of sws_1Fr, you must reset the machine by pressing the recessed reset button to effect the +change. + + +The "factory" setting of sws_1F is 4 (which selects the S3 font). + + +$WS_SD + + +Pressing SHIFT-CTRL-PSION-S on an MC, S3, S3a, S3c, Siena or a Workabout saves the current screen to a +file called screen.pic in the current path of the window server. Any existing file of the same name is +replaced. + + +In practice, the current path of the window server on a SIBO machine is always LOC::M:\ (it is defined +when the window server process is started - well before you have any chance of influencing it). + + +However, if an environment variable with the name $WS_SD exists, the window server uses its value to +open the file to be created. For example, running the following program: + + +#include + + +GLDEF_C INT main(VOID) +{ +p_setenv ("SWS_SD", "B:\\SCREEN.PIC"); +return (0); + + +} + + +subsequently causes the screen dump to be written to the root directory of the local B: drive. + + +If the save fails for any reason (such as disk full), the file is not produced and no notification of the failure +is given. + + +You can use this behaviour to disable the SHIFT-CTRL-PSION-S screen dump key by setting up sws_sp to +contain an illegal file specification. For example, just inserting the following line of code: + + +p_setenv("SWS_SD",""); + + +disables the screen dump key. + + +B ENVIRONMENT VARIABLES + + +$WS_SF, $WS_SF2 and $WS_SF4 + + +On the HC, the Siena and the Series 3, Series 3a and Series 3c, the system font is determined by the +$wWS_SF environment variable which should contain a worp binary value of 0 for ws_rFoNT_BASE, a WORD +binary value of | for ws_rontT_BasE+1, and so on. If you change the value of sws_sF, you must reset the +machine by pressing the recessed reset button to effect the change. + + +On the MC, the system font is determined in the same way, except that two alternative environment +variables are used; sws_sr2 and sws_sr4. If the screen has fewer than 300 lines (as on the MC200), +$ws_sF2 is used. Otherwise (as on the MC400), sws_sra is used. + + +The following program illustrates how the environment variable may be changed. +#include +GLDEF_C INT main(VOID) +{ + + +WORD flags; + + +flags=1; /* choose WS_FONT_BASE+1 */ +return (p_setenviron("SWS_SF",6,&flags,2)); +} + + +Changing the system font may have an adverse effect on existing applications. + + +HWIM + + +M$V + + +Evaluator format preferences, stored as an HWIM extTENDED_MEM_VALUES Structure. This environment +variable is read and written by the ws_eval_env method of the wssrv class. The default values are: + + +evalDegrees DEGREES_MODE +calcDegrees DEGREES_MODE +memVal.evalFormat P_DTOB_FIXED +memVal.evalDPlaces EVAL_DEFAULT_PLACES +memVal.calcFormat P_DTOB_GENERAL +memVal.calcDPlaces CALC_DEFAULT_PLACES +memVal.values[0] to 0.0 +memVal.values[9] + + +D$X + + +Telephone dialling preferences, stored as a DIAL_ENvaR structure. The environment variable is read and +written by ws_dial_env method of the wszrv class. The normal default values are: + + +toneLengthTicks 8 +delayLengthTicks 8 +pauseLengthTicks 48 +dialoutCode[] “9,” + + +These values may vary in non-English machines. +L$X + + +This environment variable is read by the Series 3c only, to provide a possible extra option for the ‘Use’ +choice list of the System Screen’s ‘Communications’ dialog. + + +EPOC O/S SYSTEM SERVICES + + +If it exists, the environment variable should contain three leading byte counted items which are, in order: +e text for the extra option, which will be appended to the choice list +e the full file specification of the file to p_execc if the new option is selected +e any additional command line data + + +For example, to add an ‘IRcom’ option that, on selection, executes the file loc::m:\sys$irc.img, passing it +the command line “-P1”, the environment variable could be set (using an HC-style Command +Processor).by: + + +set LS$X=\05IRCom\13L0C: :M:\SYSS$IRC.IMG\03-P1 + + +Additional command line options can be appended to any specified in the environment variable by use of +the ‘Extra parameters’ line in the System screen’s ‘Communications’ dialog. + + +ees] +Printing +P$D + + +The type of the port used for printing, held as a zero terminated character containing a single ASCTI digit. +The possible port types and their representations are: + + +PRINTER_PORT_PARALLEL ‘0’ +PRINTER_PORT_SERIAL ‘Tl +PRINTER_PORT_FILE 2’ +PRINTER_PORT_FAX ‘3’ + + +The default value represents PRINTER_PORT_PARALLEL. + + +These environment variables are set/created by the pRINTER pr_set_port_type method, and got by the +PRINTER pr_port_data method, (see the FORM Reference manual). + + +P$F + + +The name of the print file, that is, the file to which printing is to be directed, held as a zero terminated +character string. The default print file name is p.lis. + + +This environment variable is set/created by the PRINTER pr_store_file method, and got by the pRINTER +pr_port_data method, (see the FORM Reference manual). + + +P$S + + +The characteristics of the serial port when it is used for printing, held as a p_srcuar structure. The default +values are: + + +tbaud P_BAUD_9600 + +rbaud P_BAUD_9600 + +frame P_DATA_8 + +parity 0) + +hand P_OBEY_XOFF | P_OBEY_DSR|P_IGN_CTS +xoff 0x13 + +xon Ox1l1 + +flags 0 + +tmask 0 + + +This environment variable is set/created by the PRINTER pr_store_srchar method, and got by the PRINTER +pr_port_data method, (see the FORM Reference manual). + + +B ENVIRONMENT VARIABLES + + +P$M + + +The specification of the current printer model, held as a zero terminated character string. The string +contains an ASCII digit, followed by the name of a printer driver (.wdr) file, where the digit specifies the +index number, starting from zero, of the particular model within the printer driver file. The default value +is “OBJ.WDR’” (the file bj.wdr is present in the ROM of all relevant machines and contains only one +model -that for the BJ-10e printer). + + +This environment variable is set/created by the PRINTER pr_set_mode1 method, and got by the pRINTER +pr_sense_model method, (see the FORM Reference manual). + + +P$P + + +This environment variable contains two bytes of data that specify the display preferences for print +preview. The first byte is an ASCII digit specifying the number of pages to display. This must be in the +range ‘1’ to ‘4’ inclusive. The second byte is also an ASCII digit, which may be ‘1’, indicating that +margins are to be visible during print preview, or ‘0’. + + +This environment variable is set/created by the prvvIEw wn_init method (see the XADD Reference +manual). + + +P$PP + + +The port used for parallel printing, specified as a single ASCII character, for example, ‘B’. This +environment variable should only be set on machines that have more than one port, such as the +Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the printer class, in +the FORM library. + + +P$SP + + +The port used for serial printing, specified as a single ASCII character, for example, ‘A’. This +environment variable should only be set on machines that have more than one port, such as the +Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the pRintER class, in +the FORM library. + + +P$Z +The paper size, stored as a single ASCII digit. It is normally ‘0’ (A4) or ‘4’ (Letter). + + +This environment variable is only used on the Siena and the Series 3c. It is not supported on Siena +machines with a version number of 4.20 and below. + + +PSIP + + +A single ASCII character, specifying the port letter for the IR printing device. This environment variable +is used on the Siena and the Series 3c only. + + +P$PX + + +This environment variable contains the device type and the serial characteristics for ‘Parallel’ printing. It +is used only on the Siena and the Series 3c, which communicate with the Parallel cable via a serial +interface. + + +The environment variable contains a one byte device type (0 is parallel) followed by a p_srcuar struct, as +defined in p_serial.h. + + +EPOC O/S SYSTEM SERVICES + + +Calculator application +C$CALC + + +This environment variable is used on the Siena and Series 3c machines only, to store Calculator display +preferences. It contains the following structure: + + +typedef struct + + +INT bitmapId; + + +INT currentView; /* store current Calc View */ + +INT statusWinSize; /* store status window size */ + +INT nDec; /* -l=off, or 0..4 fixed dec places */ +INT Zoom; /* zoom setting for Advanced view */ + + +DOUBLE memory; +}CR_CALC_ENV_INFO; + + +whose members have the following meanings: +BitmapId for internal use only +CurrentView 0=Desk view, 1=Advanced view + + +StatusWinSize one of the Window server flags: w_sTATUS_WINDOW_OFF, W_STATUS_WINDOW_SMALL, +or (Series 3c only) w_sTATUS_WINDOW_BIG + + +NDec used by the Desk view: values can be 0 to 4 inclusive, to specify the fixed number of +decimal places to display, or -1 to display a variable number of decimal places + + +Zoom used by the Advanced view to contain the ID of the font used in the current zoom +state. For the Siena, the allowed range of values is FonT_ID_swiss_s8 to +FONT_ID_SWISS_8+3 inclusive, and for the Series 3c the range is FONT_ID_SWISS_8 +to FONT_ID_SwWIss_8+4 inclusive + + +Memory the current contents of the Desk view’s memory. + + +M$0MO0 to M$9M9 + + +These environment variables contain the current values of the ten (Advanced view) calculator memories. + + +Note that the names of these environment variables are dependent on the names of the memories, as seen +from within the Calculator application. If, for example, memory M2 is renamed to “Memory2”, the +environment variable ms2m2 will be replaced by an environment variable with the name ms2mEmory2. + + +The name of each of these environment variables will never exceed eleven characters. + + +Tips application + +TW$S + +Contains permanent data for the Tips application. The data consists of a single byte containing two flags: +0x02 if set, the display of tips is enabled + + +0x04 if set, tips are displayed once per day, otherwise they are displayed whenever the +machine is turned on + + +B ENVIRONMENT VARIABLES + + +World application + +Wsc + +Contains the display preferences for the World application, as three worps: +clock type either wS_CLOCK_FORCE_ANALOG Of WS_CLOCK_FORCE_DIGITAL +map colour either TRUE for a grey map or Fa.se for a black map + + +distance units — one of wR_uNITS_MILES (0), WR_LUNITS_KILOMETERS (1) or WR_UNITS_NAUTICAL (2) + + +WS$R + + +This environment variable stores permanent data for the World database services. The content has three +elements: + + +e asignature for the world database file, including the file version, +e data specifying the home city, + + +e data specifying the default country, that is, the country to which telephone numbers are assumed +to belong if a particular country is not specified. + + +Spell/Thesaurus +SP$DRV + + +This environment variable identifies the drive that contains the Spellchecker’s global dictionary, as set +from the Spell application’s Install menu option. It contains a single ASCII character that may be ‘A’, ‘B’ +or ‘M’. + + +SP$OPT + + +This environment variable stores the preferences settings from the Spell application as a series of flags, +stored in a single uworp. The contents affect the spellchecker and thesaurus (although not necessarily used +by both) + + +The content is an ored combination of the following set of values, selected by the user from the Spell +application’s Preferences menu option: + + +0x0100 if set, ignore words all in upper case +0x0200 if set, ignore words containing punctuation +0x0400 if set, ignore repeated words + +0x0800 if set, ignore the case of repeated words +0x1000 if set, show the definitions window +WP$SPEL + + +This is used by all applications that may wish to access the Spellchecker. The content is a single byte with +a value of zero, but has no significance; the mere existence of the environment variable indicates that the +Spellchecker is currently installed. + + +WP$THES + + +This is used by all applications that may wish to access the Thesaurus. The content is a single byte with a +value of zero, but has no significance; the mere existence of the environment variable indicates that the +Thesaurus is currently installed. + + +EPOC O/S SYSTEM SERVICES + + +———— ee re] +3Fax application + + +FSX + + +This environment variable contains two bytes of preferences. + + +The first byte contains one of the ASCII characters ‘M’, ‘A’ or ‘B’, representing the drive that is currently +used to store the application’s intermediate files. + + +The second byte contains a combination of the following flags: + + +0x01 if set, a new fax job is created on selection of ‘Print to fax’. Otherwise, the +document is simply processed to produce an intermediate file, for later +sending + +0x02 if set, intermediate files are automatically deleted after they have been sent + +F$XM + +Contains the current 3Fax modem parameters. + +F$XP + + +Stores power usage data for the 3Fax device. Contains the time on batteries and the time on mains. + + +Se ee ee eT) +Email applications + + +MAIL$ST + + +This environment variable is used, with some differences in content, by both the Corporate and the +Internet PsiMail applications. It is created by an email application whenever a mail session completes, to +contain data passed from the message transfer agent (MTA) to the mail client. It is not a permanent store +of data, as it is deleted and recreated every time the MTA starts. + + +A MAILSST environment variable created by the Corporate mail application will not disrupt the Internet +mail application, should it be run on the same machine, and vice versa. + + +The content for the Corporate application consists of a sequence of five uworns, in the following order: +e acount of the messages that were sent +e acount of the messages that were received +e acount of the messages that were not sent +e acount of the messages that are marked as read +e¢ a flag which, if set to TRUE, indicates that some messages were not received +The content for the Internet application consists of a sequence of eight uworps, in the following order: +e acount of the messages that were sent +e acount of the messages that were received +e acount of the messages that were not sent +e acount of the messages that are marked as read +e acount of messages that were deleted from the mail server +e the return code from the MTA +e the return code from the sending process (normally 0) +e the return code from the receiving process (normally 0) + + +As can be seen from the above lists, the first four items are common to both variants of MarLsst. + + +B ENVIRONMENT VARIABLES + + +Workabout + + +The following environment variables are used only on Workabout machines. See also pspp and pssp, +described in the Printing section of this chapter. + + +S$SVER + + +Contains a text string representing the Workabout Startup Shell version number, for example, “1.00F”. + + +C$P@ + + +This environment variable is set when exiting from the Workabout command processor. It contains a +single ASCII character representing the current drive, with a default value of ‘M’. + + +C$PA to C$PZ + + +The environment variable cspa may be set when exiting from the Workabout command processor, to +contain a text string representing the current path on drive A. It is not set if the drive A path is to the root +directory. + + +Similar environment variables may be set for all other possible drives - cspg to cspz inclusive. +C$P£ + + +This environment variable contains the parameters used by Link when accessed from the Workabout +System Screen and/or Command Processor. + + +C$P$ + + +This environment variable is set following selection of the keyboard from the Command Processor or the +System Screen. It contains a single byte whose binary value is either 0 (Standard keyboard selected) or | +(Special keyboard selected). + + +INDEX + + +$WS_FL + +environment variable, B-1 +$WS_FNTS + +environment variable, B-2 +$WS_IF + +environment variable, B-2 +$WS_SD + +environment variable, B-2 +$WS_SF + +environment variable, B-3 +$WS_SF2 + +environment variable, B-3 +$WS_SF4 + +environment variable, B-3 +.wve files + +sound file format, 8-1 +active + +marking a process, 19-7 + +unmarking a process, 19-8 +add + +two floats, 14-2 +adjust + +a heap memory cell size, 3-2 + +size of a memory segment, 2-6 +alarm + +getting the server pid, 19-15 + +hooking the interface, 19-15 + +unhooking the interface, 19-15 +allocate + +a heap memory cell, 3-1 + +re-allocating a heap memory cell, 3-2 +am + +getting the amtext, 19-11 +append + +a DBFrecord, 20-10 +arcsine + +float function, 15-1 +arctangent + +float function, 15-1 +asynchronous + +I/O, 8-2 + +1/O without error reporting, 8-2 + +message reception, 5-2 +attach + +a file system, 9-6 +auto-switch-off + +disable/enable if mains present, 19-16 + +get state if mains present, 19-16 + +processes and, 19-8 + +processes and, 19-7 + +resetting, 19-15 + +setting value, 19-9 + + +Auto-switch-off + +Getting value, 19-9 +battery + +enable/disable reset, 21-10 + +getting type, 19-11 + +reset the status, 21-10 + +return pointer to information, 21-11 + +setting type, 19-11 +buffer + +comparing, 17-1 + +comparing folded, 17-2 + +copying, 17-1 + +justifying, 17-4 + +locating, 17-2 + +locating folded, 17-2 + +subbuffer, 17-3 + +sub-buffer folded, 17-3 + +swapping, 17-1 + +wild card match, 17-3 + +wild card match folded, 17-4 +BufferCompare + +compare buffers service, 17-1 +BufferCompareFolded + +compare buffers folded service, 17-2 +BufferCopy + +copy buffer service, 17-1 +BufferJustify + +justify a buffer service, 17-4 +BufferLocate + +locate a character in buffer service, 17-2 +BufferLocateFolded + + +locate a character in buffer folded service, + + +17-2 +BufferMatch + +match a wildcard buffer service, 17-3 +BufferMatchFolded + + +match a wildcard buffer folded service, 17-4 + + +BufferSubBuffer + + +find a sub-buffer in a buffer service, 17-3 + + +BufferSubBufferFolded + + +find a sub-buffer in a buffer folded service, + + +17-3 +BufferSwap + +swap buffers service, 17-1 +C$CALC + +environment variable, B-6 +C$P$ + +environment variable, B-9 +C$P@ + +environment variable, B-9 +C$PEL + +environment variable, B-9 +C$PA to C$PZ + +environment variables, B-9 +cancel + +message receive, 5-3 + +playing back sound file, 8-13 + +recording sound to file, 8-14 + +signal from the supervisor, 5-5 + +signal from the supervisor by type, 5-6 + +signal from the supervisor I/O, 8-11 +capitalising + +a string, 18-1 + + +EPOC O/S SYSTEM SERVICES + + +category + +copying data from, 6-7 +change + +size of a memory segment, 2-6 +character + +is a digit, 16-1 + +is a hexadecimal digit, 16-1 + +is alphabetic, 16-1 + +is alphabetic or digit, 16-2 + +is graphic, 16-3 + +is lowercase, 16-2 + +is printable, 16-1 + +is punctuation, 16-2 + +is space, 16-2 + +is uppercase, 16-2 + +to fold, 16-3 + +to uppercase, 16-3 +Character + +is control, 16-3 + +to lowercase, 16-3 +CharIsAlpha + +character is alphabetic service, 16-1 +CharIsAlphaNumeric + +character is alphabetic or digit service, 16-2 +CharIsControl + +character is control service, 16-3 + + +CharIsDigit + +character is a digit service, 16-1 +CharIsGraphic + +character is graphic service, 16-3 +CharIsHexDigit + + +character is a hexadecimal digit service, + +16-1 +CharIsLowerCase + +character is lowercase service, 16-2 +CharIsPrintable + +character is printable service, 16-1 +CharIsPunctuation + +character is punctuation service, 16-2 +CharIsSpace + +character is space service, 16-2 +CharIsUpperCase + +character is uppercase service, 16-2 +CharToFoldedChar + +character to fold service, 16-3 +CharToLowerChar + +character to lower service, 16-3 +CharToUpperChar + +character to upper service, 16-3 +close + +a database file, 20-4 + +afile, 8-8 + +a locked or device segment, 2-5 + +a memory segment, 2-4 + +an I/Odevice, 8-8 +coldstart + +getting the reason for, 19-2 +command line + +getting, 19-6 +compare + +two buffers, 17-1 + +two buffers case independent, 17-2 + +two floats, 14-1 + +two long integers, 13-1 + + +two strings, 18-1 + +two strings case independent, 18-2 + +two unsigned long integers, 13-2 +compress + +a database file, 20-5 +connect + +to the file server, 9-1 +ConvArgumentsToBuffer + +convert arguments to buffer service, 12-2 +conversion + +arguments to buffer, 12-2 + +floating point number to buffer, 12-4 + +integer to buffer, 12-1 + +long integer to buffer, 12-2 + +string to floating point number, 12-5 + +string to integer, 12-3 + +string to long integer, 12-3 + +string to unsigned integer, 12-2 + +string to unsigned long integer, 12-2 + +unsigned integer to buffer, 12-1 + +unsigned long integer to buffer, 12-1 +convert + +a string to folded, 18-1 + +float to signed integer, 14-3 + +float to signed long, 14-2 + +float to unsigned integer, 14-3 + +float to unsigned long, 14-2 + +signed integer to float, 14-3 + +signed long to float, 14-3 + +unsigned integer to float, 14-3 +ConvFloatToBuffer + +convert floating point number to buffer + +service, 12-4 +ConvintToBuffer + +convert integer to buffer service, 12-1 +ConvLongIntToBuffer + +convert long integer to buffer service, 12-2 +ConvStringToFloat + +convert string to floating point number, + +12-5 +ConvStringToInt + +convert string to integer, 12-3 +ConvStringToLongInt + +convert string to long integer, 12-3 +ConvStringToUnsignedInt + +convert string to unsigned integer, 12-2 +ConvStringToUnsignedLongInt + +convert string to unsigned long integer, + +12-2 +ConvUnsignedIntToBuffer + +convert unsigned integer to buffer service, + +12-1 +ConvUnsignedLongIntToBuffer + +convert unsigned long integer to buffer + +service, 12-1 +copy + +a buffer, 17-1 + +a database file, 20-5 + +a string, 18-1 + +a string folded, 18-1 + +copying down a DBF record, 20-5 + +data from a process, 10-8 + +data to a process, 10-9 + +from a category, 6-7 + + +from a memory segment, 2-7 +strings from a process, 10-9 +to a memory segment, 2-6 +cosine +float function, 15-1 +count +the number of DBF records, 20-13 +country data +getting, 19-2 +setting, 19-2 +CRC +generating, 19-12 +create +a memory segment, 2-3 +an object by handle, 6-3 +an object by number, 6-3 +a process, 10-4 +a semaphore, 4-1 +a task, 10-4 +D$xX +environment variable, B-3 +data segment +of the operating system, 19-2 +Database file +appending a record, 20-10 +closing, 20-4 +compressing, 20-5 +copying, 20-5 +copying down a record, 20-5 +counting the number of records, 20-13 +Deleted records, 20-5 +end of file, 20-2 +erasing a record, 20-11 +file buffering, 20-2 +file structure, 20-1 +finding a record, 20-12 +finding a record by field, 20-13 +flushing, 20-4 +getting the size, 20-6 +Getting the version number, 20-8 +index table, 20-2 +number of records, 20-3 +opening, 20-3 +reading an absolute record, 20-8 +reading and sensing an absolute record, +20-9 +reading the descriptive record, 20-7 +reading the extended header, 20-7 +reading the first record, 20-10 +reading the last record, 20-10 +reading the next record, 20-9 +reading the previous record, 20-9 +sensing the record number, 20-13 +trashing the buffer, 20-4 +updating a record, 20-11 +writing the descriptive record, 20-8 +Writing the extended header, 20-7 +date +abbreviated name of day, 11-5 +abbreviated name of month, 11-5 +convert date to day seconds, 11-3 +convert day seconds to date, 11-3 +convert day seconds to system time, 11-3 + + +INDEX + + +convert the system time to day seconds, +11-3 +getting am and pm text, 19-11 +getting suffixes, 19-11 +getting the systemdate, 11-2 +name of day, 11-4 +name of month, 11-4 +number of days in a month, 11-4 +set file, 9-8 +setting the system date, 11-2 +weekday number, 11-4 +day +abbreviated name of, 11-5 +name of, 11-4 +days +number of, 11-4 +DbfAbsRead +reading an absolute DBF record service, +20-8 +DbfAbsReadSense +reading and sensing an absolute DBF record +service, 20-9 +DbfAppend +append a DBF record service, 20-10 +DbfBackRead +read the previous DBF record service, 20-9 +DbfClose +closing a database file service, 20-4 +DbfCompress +compressing a database file service, 20-5 +DbfCopyDown +copying down a DBF record service, 20-5 +DbfCopyFile +copying a database file service, 20-5 +DbfCount +count the number of DBF records service, +20-13 +DbfDescRecordRead +reading a DBF descriptive record service, +20-7 +DbfDescRecord Write +writing a DBF descriptive record service, +20-8 +DbfEraseRead +erasing a DBF record service, 20-11 +DbfExtHeaderRead +reading a DBF extended header service, +20-7 +DbfExtHeaderWrite +writing a DBF extended header service, +20-7 +DbfFileSize +getting the size of a database file service, +20-6 +DbfFindRead +finding a DBF record service, 20-12 +DbfFindReadField +finding a DBF recordbyfield service, 20-13 +DbfFirstRead +read the first DBF record service, 20-10 +DbfFlush +flushing a database file service, 20-4 +DbfLastRead +read the last DBF record service, 20-10 + + +iii + + +EPOC O/S SYSTEM SERVICES + + +DbfNextRead + +read the next DBF record service, 20-9 +DbfOpen + +opening a database file service, 20-3 +DbfSense + +sense the current DBF record number + +service, 20-13 +DbfTrash + +trashing the DBF buffer service, 20-4 +DbfUpdate + +updating a DBF record service, 20-11 +DbfVersion + +getting the DBF version number service, + +20-8 +deferred mode + +setting, 19-4 +delete + +a device driver, 7-3 + +a file or directory, 9-3 + +a memory segment, 2-4 + +a semaphore, 4-1 +destroy + +an object, 6-4 +detach + +a file system, 9-7 +DevDelete + +delete a device driver service, 7-3 +DevFind + +find all devices service, 7-4 +DevGetPDDAddress + +get PDD entry point service, 7-2 +DevHold + +hold all device drivers service, 7-2 +devices + +calling a vector, 7-5 + +delete a device driver, 7-3 + +drivers, 7-1 + +find all devices, 7-4 + +getting the PDD entry point, 7-2 + +hold all device drivers, 7-2 + +install a device driver, 7-2 + +load a logical device driver, 7-3 + +load a physical device driver, 7-3 + +names, 7-1 + +open a physical device driver, 7-1 + +query the number of units, 7-4 + +remove a device driver, 7-4 + +resume all device drivers, 7-3 +devices and files + +and I/O, 8-1 +DevInstall + +install a device driver service, 7-2 +DevLoadLDD + +load a logical device driver service, 7-3 +DevLoadPDD + +load a physical device driver service, 7-3 +DevOpenPDD + +open PDD service, 7-1 +DevQueryUnits + +query the number of units service, 7-4 +DevRemove + +remove a device driver service, 7-4 +DevResume + +resume all device drivers service, 7-3 + + +DevVector +call a device vector, 7-5 +directory +changing, 9-7 +deleting, 9-3 +getting status, 9-4 +making, 9-6 +renaming, 9-4 +setting status, 9-4 +display type +getting, 19-2 +divide +floats, 14-1 +two long integers, 13-1 +two unsigned long integers, 13-2 +dummy +call, 19-3 +service, 19-3 +DYL +getting a handle, 6-3 +dynamic library +finding, 6-2 +getting a handle, 6-3 +linking, 6-2 +loading, 6-1 +loading multiple, 6-6 +names, 6-1 +unloading, 6-2 +EM$ +environment variable, B-1 +endoffile +database file, 20-2 +enter +a control region, 6-7 +leaving from a control region, 6-7 +environment variable +$WS_FL, B-1 +$WS_FNTS, B-2 +$WS_IF, B-2 +$WS_SD, B-2 +$WS_SF, B-3 +$WS_SF2, B-3 +$WS_SF4, B-3 +C$CALC, B-6 +C$P$, B-9 +C$P@, B-9 +C$PE£, B-9 +C$PA to C$PZ, B-9 +contents and names of all, B-1 +D$X, B-3 +deleting buffer, 19-13 +deleting string, 19-14 +EM$, B-1 +F$X, B-8 +F$XM, B-8 +F$XP, B-8 +finding buffer, 19-13 +finding string, 19-14 +getting buffer, 19-12 +getting string, 19-14 +L$X, B-3 +M$0MO, B-6 +M$1M1, B-6 +M$2M2, B-6 + + +MAILSST, B-8 + + +names and contents of all, B-1 + + +P$D, B-4 +P$F, B-4 +P$IP, B-5 +P$M, B-5 + + +S$SVER, B-9 + +setting buffer, 19-12 + +setting string, 19-14 + +SP$DRV, B-7 + +SP$OPT, B-7 + +TW$S, B-6 + +WSC, B-7 + +WSR, B-7 + +WPS$SPEL, B-7 + +WP$THES, B-7 +Environment variable + +Finding all, 19-13 +epocsibo.inc + +Include file, 21-10 +erase + +aDBFrecord, 20-11 +error + +notificationof, 19-5 +errors + +gettingthetext, 19-3 +execute + +animagefile, 9-1 +exits + +watchingall, 10-8 +expansion port + +sense state of, 21-12 +exponentiation + +floatfunction, 15-2 +F$X + +environment variable, B-8 +F$XM + +environment variable, B-8 +F$XP + +environment variable, B-8 +FilChangeDirectory + + +change directory service, 9-7 + + +FilConnect + + +file server connect service, 9-1 + + +FilDelete + + +delete file or directory service, 9-3 + + +filebuffering + +database file, 20-2 +filemanagement + +attaching a file system, 9-6 + + +INDEX + + +change directory, 9-7 + +connect to the file server, 9-1 + +deleting, 9-3 + +detaching a file system, 9-7 + +execute a program file, 9-1 + +get current path, 9-2 + +get current path by ID, 9-7 + +getting device status, 9-5 + +getting status, 9-4 + +getting system status, 9-5 + +local file system changed, 9-8 + +making a new directory, 9-6 + +parse a filename, 9-2 + +read a local device directly, 9-9 + +read media information of a local device, + +9-9 + +renaming, 9-4 + +set current path, 9-3 + +set file date, 9-8 + +set initial path, 9-8 + +setting status, 9-4 + +test path available, 9-3 +filename + +generic parse, 19-3 +fileserver + +process, 9-1 +filestructure + +database file, 20-1 +FilExecute + +execute image file service, 9-1 +FilLocChanged + +report if the local file system has changed, + +9-8 +FilLocDevice + +read media information of a local device, + +9-9 +FilLocReadPdd + +read a local device directly, 9-9 +FilMakeDirectory + +make a new directory service, 9-6 +FilOpenUnique + +I/O open a unique filename service, 9-6 +FilParse + +parse filename service, 9-2 +FilPathGet + +get current path service, 9-2 +FilPathGetByld + +get current path by ID service, 9-7 +FilPathSet + +set current path service, 9-3 +FilPathTest + +test path available service, 9-3 +FilRename + +rename a file or directory service, 9-4 +FilSetFileDate + +set file date service, 9-8 +FilSetInitialPath + +set initial path service, 9-8 +FilStatusDevice + +get device status service, 9-5 +FilStatusGet + +get file or directory status service, 9-4 +FilStatusSet + +setfile or directory status service, 9-4 + + +EPOC O/S SYSTEM SERVICES + + +FilStatusSystem +get file system status, 9-5 +FilSystemAttach +attach a file system service, 9-6 +FilSystemDetach +detach a file system service, 9-7 +find +a DBF record, 20-12 +a DBF record by field, 20-13 +a dynamic library, 6-2 +all Devices, 7-4 +all processes, 10-7 +all segments, 2-6 +float +adding, 14-2 +arc sine function, 15-1 +arc tangent function, 15-1 +comparing, 14-1 +conversion to a buffer, 12-4 +converting signed integer to float, 14-3 +converting signed long to float, 14-3 +converting to signed integer, 14-3 +converting to signed long, 14-2 +converting to unsigned integer, 14-3 +converting to unsigned long, 14-2 + + +converting unsigned integer to float, 14-3 + + +cosine function, 15-1 + +dividing, 14-1 + +exponentiation function, 15-2 +logarithm function, 15-2 +modulo function, 15-3 +multiplying, 14-1 + +natural logarithm function, 15-2 +negating, 14-2 + +power function, 15-3 + +random number function, 15-3 +sine function, 15-3 + +square root function, 15-4 +subtracting, 14-2 + +tangent function, 15-4 + +to integer, 15-2 + + +FloatAdd + +add floats service, 14-2 +FloatASin + +arc sine service, 15-1 +FloatATan + +arc tangent service, 15-1 +FloatCompare + +compare floats service, 14-1 +FloatCos + +cosine service, 15-1 +FloatDivide + +divide floats service, 14-1 +FloatExp + +exponentiation service, 15-2 +FloatInt + +integer service, 15-2 +FloatLn + +natural logarithm service, 15-2 +FloatLog + +logarithm service, 15-2 +FloatMod + + +modulo service, 15-3 + + +FloatMultiply + +multiply floats service, 14-1 +FloatNegate + +negate floats service, 14-2 +FloatPow + +power service, 15-3 +FloatRand + +random number service, 15-3 +FloatSin + +sine service, 15-3 +FloatSqrt + +square root service, 15-4 +FloatSubtract + +subtract floats service, 14-2 +FloatTangent + +tangent service, 15-4 +FloatToInt + + +convert float to signed integer service, 14-3 + + +FloatToLong +convert float to long service, 14-2 +FloatToUnsignedInt + + +convert float to unsigned integer service, + + +14-3 +FloatToUnsignedLong + +convert float to long service, 14-2 +flush + +a database file, 20-4 +free + +a heap memory cell, 3-3 + +a message, 5-4 +GenAlarmHook + +hook the alarm interface, 19-15 +GenAlarmld + +get the pid of the alarm server, 19-15 +GenCrc + +generate a CRC check, 19-12 + + +GenDataSegment + +operating system data segment, 19-2 +GenDeferredMode + +set deferred mode, 19-4 +GenEnvBufferDelete + +delete environment variable, 19-13 +GenEnvBufferFind + +find environment variable, 19-13 +GenEnvBufferGet + +get environment variable, 19-12 +GenEnvBufferSet + +set environment variable, 19-12 +GenEnvStringDelete + +delete environment variable, 19-14 +GenEnvStringFind + +find environment variable, 19-14 +GenEnvStringGet + +get environment variable, 19-14 +GenEnvStringSet + +set environment variable, 19-14 +GenGetAmPmText + +get the am and pm text, 19-11 +GenGetAutoMains + + +get state for auto-switch-off if mains + +present, 19-16 +GenGetAutoSwitchOffValue + +get the auto switch off value, 19-9 + + +GenGetBatteryType + +get the battery type, 19-11 +GenGetCommandLine + +get the command line, 19-6 +GenGetCountryData + +get country dependent data, 19-2 +GenGetErrorText + +get error text, 19-3 +GenGetLanguageCode + +get the language code, 19-10 +GenGetNotifyState + +get notify state, 19-8 +GenGetOsData + +get O/S data, 19-3 +GenGetRamSizelInParas + +get address able system RAM size, 19-6 +GenGetSoundFlags + +get the sound flags, 19-7 +GenGetSuffixes + +get suffix text, 19-11 +GenGetText + +get operating system text, 19-8 +GenIntByNumber + +interrupt by number, 19-12 +GenLcdType + +LCD type, 19-2 +GenMarkActive +mark process as active, 19-7 +GenMarkNonActive +mark process as non-active, 19-8 +GenNotify +notification service, 19-4 +GenNotifyError +notification of error, 19-5 +GenNotifyHook + +hook the notifier interface, 19-5 +GenParse + +generic parse, 19-3 + + +GenResetRevector + +release an interrupt, 19-10 +GenRom Version + +get the ROM version, 19-1 +GenSetAutoMains + + +disable/enableauto-switch-off if mains + +present, 19-16 +GenSetAutoSwitchOffValue + +set the auto switchoff time, 19-9 +GenSetBatteryType + +set the battery type, 19-11 +GenSetCountryData + +set country dependent data, 19-2 +GenSetNotifyState + +set notify state, 19-9 +GenSetOnEvents + +enable/disable on events, 19-16 +GenSetRevector + +capture an interrupt, 19-9 +GenSetSoundFlags + +set the sound flags, 19-7 +GenSound + +make a sound with the piezo, 19-7 +GenStartReason + +getting the system cold start reason, 19-2 + + +INDEX + + +GenTickle + +reset the autoswitch off timer, 19-15 +GenUnAlarmHook + +unhook the alarm interface, 19-15 +GenUnNotifyHook + + +unhook the notifier interface, 19-6 +GenVersion +operating system version number, 19-1 +granularity +of the heap memory, 3-3 +halfseconds +query completion, 8-12 +signal on next half second, 8-11 +handle +of a DYL, 6-3 +of a dynamic library, 6-3 +handler +adding, 8-6 +adding an application, 8-9 +enabling, 8-6 +enabling an application, 8-10 +removing, 8-6 +removing an application, 8-10 +hardware +capturing the combo subsystem, 21-5 +changing the LCD contrast, 21-6 +clearing bits in Asic2 register1, 21-2 +clearing bits in Asic2 register2, 21-3 +clearing bits in Asic2 register3, 21-3 +enable/disable reset, 21-10 +exiting toDOS, 21-5 +expansion port sense state of, 21-12 +freeing a channel, 21-6 +freeing the combo subsystem, 21-5 +get additional power supply data, 21-10 +getting achannel, 21-5 +getting backlight control, 21-7 +getting current LCD contrast, 21-7 +getting supplies status, 21-6 +getting supplies warnings, 21-6 +getting the power supply type, 21-6 +Honda connector power disable, 21-12 +Honda connector power enable, 21-12 +infrared power level set, 21-11 +operating the backlight, 21-7 +reading Asic2 register2, 21-3 +reading Asic2 register3, 21-4 +reset the battery status, 21-10 +return battery information, 21-11 +scan state of all keys, 21-8 +select serial channel, 21-4 +sending a serial null frame, 21-4 +setting backlight control, 21-7 +setting bits in Asic2 register1, 21-2 +setting bits in Asic2 register2, 21-2 +setting bits in Asic2 register3, 21-3 +SSDs relog, 21-11 +switching off, 21-4 +switching off the combo, 21-1 +switching off the SSDs, 21-1 +switching on the combo, 21-1 +switching on the combo in input mode, +21-10 +switching on the SSDs, 21-1 + + +EPOC O/S SYSTEM SERVICES + + +tick count sense current, 21-11 +writing Asic2 register 1, 21-2 +writing Asic2 register2, 21-3 +writing Asic2 register3, 21-4 + + +Hardware + +Reading Asic2 register1, 21-2 +HeapAdjustCellSize + +adjust heap cellsize service, 3-2 +HeapAllocateCell + +allocate heap cell service, 3-1 +HeapCellSize + +size of heap memory cell, 3-3 +HeapFreeCell + +free a heap cell service, 3-3 +HeapFreeMemory + + +size of available heap memory, 3-3 +heap memory + +dynamics, 3-1 +HeapReAllocateCell + +re-allocate heap cell service, 3-2 +HeapSetGranularity + +set heap grow by parameter service, 3-3 +Honda connector + +power disable, 21-12 + +power enable, 21-12 +HwBackLight + +operating the backlight, 21-7 +HwClearA2Control1 Bits + +clearing bits in Asic2 register 1, 21-2 +HwClearA2Control2Bits + +clearing bits in Asic2 register 2, 21-3 +HwClearA2Control3Bits + +clearing bits in Asic2 register 3, 21-3 +HwComboOff + +switch off the combo, 21-1 +HwComboOn + +switch on the combo, 21-1 +HwComboOnInput + + +switch on the combo in input mode, 21-10 + + +HwEnableAutoBatReset + +enable/disable battery reset on recharge, + +21-10 +HwExit + +exit the program, 21-5 +HwExpansionOff + +Honda connector power disable, 21-12 +HwExpansionOn + +Honda connector power enable, 21-12 +HwFreeChannel + +free a channel, 21-6 +HwFreeCombo + +free the combo, 21-5 +HwGetBackLight + +get backlight control, 21-7 +HwGetBatData + +return battery information, 21-11 +HwGetChannel + +get a channel, 21-5 +HwGetCombo + +capture the combo, 21-5 +HwGetPsuType + +get power supply type, 21-6 +HwGetScanCodes + +scan the state of all keys, 21-8 + + +viii + + +HwGetSupplyStatus + +get supplies status, 21-6 +HwLcdContrastDelta + +change the LCD contrast, 21-6 +HwNullFrame + +send a serial null frame, 21-4 +HwPacksOff + +switch off the SSDs, 21-1 +HwPacksOn + +switch on the SSDs, 21-1 +HwReadA2Control1 + +read Asic2 register 1, 21-2 +HwReadA2Control2 + +read Asic2 register 2, 21-3 +HwReadA2Control3 + +read Asic2 register 3, 21-4 +HwReadLcdContrast + +read current contrast, 21-7 +HwReLogPacks + +relog the SSDs, 21-11 +HwResetBatteryStatus + +reset the battery status, 21-10 +HwReturnExpansionPortState + +expansion port sense state of, 21-12 + + +HwReturnTickCount + +tick count - sense current, 21-11 +HwSelectChannel + +select serial channel, 21-4 +HwSetA2Control1 Bits + +setting bits in Asic2 register 1, 21-2 +HwSetA2Control2Bits + +setting bits in Asic2 register 2, 21-2 +HwSetA2Control3Bits + +setting bits in Asic2 register 3, 21-3 +HwSetBackLight + +set backlight control, 21-7 +HwsSetIRPowerLevel + +Set the infrared power level, 21-11 +HwSupplyInfo + +get additional power supply data, 21-10 +HwSupplyWarnings + +get supplies warnings, 21-6 +HwSwitchOff + +switch off service, 21-4 +HwWriteA2Control1 + +write Asic2 register 1, 21-2 +HwWriteA2Control2 + +write Asic2 register 2, 21-3 +HwWriteA2Control3 + +write Asic2 register 3, 21-4 +V/O + + +adding a handler, 8-6 +adding an application handler, 8-9 +a synchronous, 8-2 + + +a synchronous without error reporting, 8-2 + + +cancel playing back a sound file, 8-13 +cancel recording sound to a file, 8-14 +cancel requested reset, 8-7 + +cancel request for a signal from the +supervisor, 8-11 + +chain to root device, 8-3 + +chain to super class device, 8-4 +closing a device, 8-8 + +enabling a handler, 8-6 + + +enabling an application handler, 8-10 +getting the shift states, 8-10 +keyboard and mouse, 8-9 +opening a device, 8-7 +opening a unique filename, 9-6 +play back a sound file asynchronously, 8-12 +play back a sound file synchronously, 8-12 +polling for completion, 8-5 +query the completion of IoNextHalfSecond, +8-12 +reading from a device, 8-8 +record sound to a file synchronously, 8-13 +record sound to file asynchronously, 8-14 +removing a handler, 8-6 +removing an application handler, 8-10 +request a signal the supervisor, 8-11 +requesting reset, 8-7 +request signal on next half second, 8-11 +seeking on a device, 8-8 +signalling completion, 8-5 +signalling completion by pid with no +re-schedule, 8-5 +signalling completion by process ID, 8-5 +synchronous, 8-3 +wait for completion, 8-4 +wait for completion no handlers, 8-10 +wait for specific completion, 8-4 +writing to a device, 8-8 +1/O system +messaging, 5-2 +image +opening to access multiplelibraries, 6-5 +include file +epocdefs.inc, 1-3 + + +indextable + +database file, 20-2 +infrared + +set power level, 21-11 +initialize + +the message system, 5-2 +install + +adevice driver, 7-2 +int + +by number, 19-12 +integer + + +comparing longs, 13-1 +comparing unsigned longs, 13-2 +conversion to a buffer, 12-1 +divide longs, 13-1 +divide unsigned longs, 13-2 +multiply longs, 13-1 +multiply unsigned longs, 13-2 +of a float, 15-2 +unsigned conversion to a buffer, 12-1 +unsigned long random number, 13-3 +inter process communications +messaging, 5-1 +interrupt +calling conventions, 1-1 +capturing, 19-9 +multi service, 1-1 +releasing, 19-10 +single service, 1-1 + + +INDEX + + +interrupts + +alphabetic listing, A-2 + +alphabetic listing - extra functions, A-27 + +function numbers, A-1 + +function numbers - extra functions, A-27 + +numerical listing, A-14 + +numerical listing - extra functions, A-27 + +using single or multi, A-1 +ToAddHandler + +I/O add handler service, 8-6 +IoApplicationAddHandler + +I/O add handler service, 8-9 +ToAsynchronous + +I/O asynchronous service, 8-2 +ToAsynchronousNoError + +I/O asynchronous without error reporting + +service, 8-2 +ToClose + +I/O close a device service, 8-8 +IoEnableApplicationHandler + +1/O enable/disable application handler + +service, 8-10 +IoEnableHandler + +I/O enable/disable handler, 8-6 +IoKeyAndMouseWith Wait + +get keyboard and mouse events service, 8-9 +IoNextHalfSecond + +request completion on the next half second, + +8-11 +ToNextHalfSecondStatus + +query the completion of Io Next Half + +Second, 8-12 +IoOpen + +I/O open a device service, 8-7 +IoPlaySoundA + +play back a sound file asynchronously, 8-12 +IoPlaySoundCancel + +cancel playing back a sound file, 8-13 +ToPlaySoundW + +play back a sound file synchronously, 8-12 +ToRead + +I/O read from a device service, 8-8 +IoRecordSoundA + +record sound to a file asynchronously, 8-14 +IoRecordSoundCancel + +cancel recording sound to a file, 8-14 +IoRecordSoundW + +record sound to a file synchronously, 8-13 +ToRemoveApplicationHandler + +I/O remove application handler service, + +8-10 +ToRequestReset + +I/O request reset service, 8-7 +IoRequestResetCancel + +I/O cancel requested reset service, 8-7 +ToRoot + +I/O chain to root device service, 8-3 +IoSeek + +I/O seek to a new position, 8-8 +ToShiftStates + +I/O get shift states service, 8-10 +ToSignal + +I/O signal completion service, 8-5 + + +EPOC O/S SYSTEM SERVICES + + +IoSignalByPid +I/O signal completion by process ID service, +8-5 +IoSignalByPidNoReSched +I/O signal completion by pid with no +reschedule service, 8-5 +IoSignalKillAsynchronous +request signal from supervisor service, 8-11 +IoSignalKillCancel +cancel signal kill from supervisor service, +8-11 +IoSuper +I/O chain to super class device service, 8-4 +ToWaitForSignal +I/O wait for completion service, 8-4 +IoWaitForSignalNoHandler +1/O wait for completion with no handlers +service, 8-10 +ToWaitForStatus +1/O wait for specific request to complete +service, 8-4 +IoWithWait +I/O with wait service, 8-3 +IoWrite +I/O write to a device service, 8-8 +IoYield +I/O update status words service, 8-5 +justify +a buffer, 17-4 +keyboard +reading, 8-9 +scanning state of all keys, 21-8 +Keyboard +scan codes HC alphabetic, 21-8 +scan codes HC numeric, 21-9 +scan codes Series 3a, 21-8 +scan codes Workabout, 21-9 +kill +aprocess, 10-6 +L$X +environment variable, B-3 +languagecode +getting, 19-10 +LCD +getting the type, 19-2 +length +of a string, 18-4 +LibCopy +copy data from a categories segment, 6-7 +LibCreate +creating an object by number service, 6-3 +LibCreateByHandle +creating an object by handle service, 6-3 +LibDestroy +destroying an object service, 6-4 +LibEnter +enter a control region, 6-7 +LibEnterSend +send message with an enclosing Lib Enter, +6-5 +LibExactSend +send message to a known class, 6-5 +LibFind +dynamic library find service, 6-2 + + +LibHandle + +dynamic library get handle service, 6-3 +LibLeave + +exit from a control region, 6-7 +LibLink + +dynamic library link service, 6-2 +LibLoad + +dynamic library load service, 6-1 +LibLoadFile + +dynamic library load from multiple library + +file, 6-6 +LibOpen + +open an image file containing multiple + +libraries, 6-5 +library + +opening in an image, 6-5 +library names + +dynamic, 6-1 +LibReClass() + +reclassing an object by number, 6-6 +LibReClassByHandle + +reclassing an object by handle, 6-7 +LibSend + +send message to an object service, 6-4 +LibSendExit + +exit from a method, 6-8 +LibSuperSend + +send message to the objects superclass + +service, 6-4 +LibUnLoad + +dynamic library unload service, 6-2 +link + +a dynamic library, 6-2 +load + +a dynamic library, 6-1 + +a logical device driver, 7-3 + +a multiple dynamic library, 6-6 + +a physical device driver, 7-3 +locate + +a character in a buffer, 17-2 + +a character in a buffer folded, 17-2 + +a character in a string, 18-3 + +a character in a string folded, 18-3 + +a character in a string in reverse, 18-3 + +a character in a string in reverse folded, + +18-3 +lock + +a memory segment, 2-5 +logarithm + +float function, 15-2 +LongIntCompare + +compare long integers service, 13-1 +LongIntDivide + +long integer divide service, 13-1 +longinteger + +conversion to a buffer, 12-2 + +unsigned conversion to a buffer, 12-1 +LongIntMultiply + +long integer multiply service, 13-1 +LongToFloat + +convert signed long to float service, 14-3 +LongUnsignedIntCompare + +compare unsigned long integers service, + +13-2 + + +LongUnsignedIntDivide +unsigned long integer divide service, 13-2 +LongUnsignedIntMultiply +long unsigned integer multiply service, 13-2 +LongUnsignedIntRandom +unsigned long integer random number +service, 13-3 +M$0OMO +environment variable, B-6 +M$IMI +environment variable, B-6 +M$2M2 +environment variable, B-6 +M$3M3 +environment variable, B-6 +M$4M4 +environment variable, B-6 +M$5M5 +environment variable, B-6 +M$6M6 +environment variable, B-6 +M$7M7 +environment variable, B-6 +M$8M8 +environment variable, B-6 +M$9M9 +environment variable, B-6 +M$V +environment variable, B-3 +MAIL$ST +environment variable, B-8 +mark +resetting the auto switch off timer, 19-15 +match +a wildcard buffer, 17-3 +a wildcard buffer folded, 17-4 +a wildcard string, 18-2 +a wildcard string folded, 18-2 +media +read a local device directly, 9-9 +read information of a local device, 9-9 +memory +adjust heap memory size, 3-2 +adjust the size of a memory segment, 2-6 +allocate heap memory, 3-1 +close a memory segment, 2-4 +copy from a memory segment, 2-7 +copy to a memory segment, 2-6 +create a memory segment, 2-3 +delete a memory segment, 2-4 +find all segments, 2-6 +free heap memory, 3-3 +heap memory dynamics, 3-1 +lock a memory segment, 2-5 +open a memory segment, 2-4 +paragraphs size of, 2-1 +re-allocate heap memory, 3-2 +segment directly accessing, 2-1 +segment locking, 2-1 +segment names, 2-1 +setting the heap granularity, 3-3 +size of available heap memory, 3-3 +size of available segmented memory, 2-2 + + +INDEX + + +size of addressable system ram, 19-6 +size of a heap cell, 3-3 +size of a memory segment, 2-5 +size of RAM disk, 2-7 +unlock a memory segment, 2-5 +message +enter send, 6-5 +sending to a known class, 6-5 +sending to an object , 6-4 +sending to an objects superclass, 6-4 +message reception +order of, 5-1 +message system +I/O system, 5-2 +messages +asynchronous reception, 5-2 +cancelling receive, 5-3 +cancel request for a signal from the +supervisor, 5-5 +cancel request for a signal from the +supervisor by type, 5-6 +freeing, 5-4 +initializing, 5-2 +request a signal the supervisor, 5-5 +sending, 5-3 +sending and getting a reply asynchronously, +5-4 +sending and waiting for a reply, 5-4 +synchronous reception, 5-3 +messaging +inter process communication, 5-1 +MessFree +free message service, 5-4 +MessInit +initialize messages service, 5-2 +MessReceiveAsynchronous +receive message asynchronously, 5-2 +MessReceiveCancel +cancel queued message receive service, 5-3 +MessReceiveWith Wait +synchronous message reception, 5-3 +MessSend +send message service, 5-3 +MessSendReceiveAsynchronous +send message and get reply asynchronously +service, 5-4 +MessSendReceiveWith Wait +send message and wait for reply service, 5-4 +MessSignal +request signal from supervisor service, 5-5 +MessSignalCancelX +cancel requested signal from Supervisor by +type service, 5-6 +method +returning from a method, 6-8, 7-1 +modulo +float function, 15-3 +month +abbreviated name of, 11-5 +name of, 11-4 +number of days, 11-4 +mouse +reading, 8-9 + + +EPOC O/S SYSTEM SERVICES + + +multiply +two floats, 14-1 +two long integers, 13-1 +two unsigned long integers, 13-2 +name +validation, 18-5 +names +device, 7-1 +memory segments, 2-1 +of processes by ID, 10-7 +naturallogarithm +float function, 15-2 +negate +floats, 14-2 +notify +by error number, 19-5 +by text messages, 19-4 +getting state, 19-8 +hooking the interface, 19-5 +setting state, 19-9 +unhooking the interface, 19-6 +number +getting suffixes text, 19-11 +of week, 11-5 +number of records +database file, 20-3 +object +creating by handle, 6-3 +creating by number, 6-3 +destroying, 6-4 +enter a sent message, 6-5 +reclassing by handle, 6-7 +reclassing by number, 6-6 +sending a message, 6-4 +sending a message to a known class, 6-5 +sending a super class message, 6-4 +on events +receiving, 19-16 +open +a database file, 20-3 +afile, 8-7 +a memory segment, 2-4 +a multi library file, 6-5 +an I/O device, 8-7 +a physical device driver, 7-1 +a unique filename, 9-6 +operating system +data segment getting, 19-2 +operating system +getting the data, 19-3 +operating system text +getting, 19-8 +owner +getting, 10-3 +P$D +environment variable, B-4 +P$F +environment variable, B-4 +P$IP +environment variable, B-5 +P$M +environment variable, B-5 +P$P +environment variable, B-5 + + +P$PP + +environment variable, B-5 +P$PX + +environment variable, B-5 +P$S + +environment variable, B-4 +P$SP + +environment variable, B-5 +P$Z + +environment variable, B-5 +panic + +a process, 10-7 + +the current process, 10-8 +paragraphs + +size of memory segments, 2-1 +parse + +a filename, 9-2 + +generic filename, 19-3 +path + +get current, 9-2 + +get current by ID, 9-7 + +set current, 9-3 + +set initial, 9-8 + +test available, 9-3 +PDD + +physical device driver, 7-1 +piezo + +sound, 19-7 +pm + +getting the pm text, 19-11 +polling + +I/O status words, 8-5 +power + +float function, 15-3 +power supply + +getting additional data, 21-10 +priority + +getting, 10-3 + +setting, 10-3 +ProcCopyFromByld + +copy data from a process service, 10-8 +ProcCopyToByld + +copy data to a process service, 10-9 +ProcCreate + +create process service, 10-4 +ProcCreateTask + +create task service, 10-4 +processes + +controlling, 10-2 + +copying data from by ID, 10-8 + +copying data to by ID, 10-9 + +copying strings from by ID, 10-9 + +creating, 10-4 + +find all, 10-7 + +get an ID by name, 10-3 + +get name by ID, 10-7 + +get owner, 10-3 + +get priority, 10-3 + +get the current process ID, 10-2 + +ID and process table, 10-2 + +IDs and names, 10-1 + +killing, 10-6 + +panicking, 10-7 + +panicking current, 10-8 + + +renaming, 10-7 + +resuming, 10-5 + +scheduling, 10-1 + +setpriority, 10-3 + +suspending, 10-5 + +terminate and kill, 10-2 + +terminating, 10-6 + +termination registration, 10-6 + +watching all exits, 10-8 +ProcFind + +find all processes service, 10-7 +ProcGetOwner + +get the PID of the owning process service, + +10-3 +ProcGetPriority + +get process priority service, 10-3 +ProclId + +get current process ID service, 10-2 +ProcIdByName + +get process ID by name service, 10-3 +ProcIndStringCopyFromByld + +copy a string from a process service, 10-9 +ProcKill + +kill process service, 10-6 +ProcNameByld + +name of a process by ID service, 10-7 +ProcOnTerminate + +register termination service, 10-6 +ProcPanic + +panic current process service, 10-8 +ProcPanicByld + +panic process service, 10-7 +ProcRename + +rename a process service, 10-7 +ProcResume + +resume process service, 10-5 +ProcSetPriority + +set process priority service, 10-3 +ProcSuspend + +suspend process service, 10-5 +ProcTerminate + +terminate process service, 10-6 +Proc WatchAIIExits + +monitor exits service, 10-8 +query + +the number of units, 7-4 +RAM disk + +return size of, 2-7 +random + +float function, 15-3 + +unsigned long integer, 13-3 +read + +a DBF descriptive record, 20-7 + +a DBF extended header, 20-7 + +an absolute DBF record, 20-8 + +from a file, 8-8 + +from an I/O device, 8-8 + +the first DBF record, 20-10 + +the last DBF record, 20-10 + +the next DBF record, 20-9 + +the previous DBF record, 20-9 +reclass + +an object by handle, 6-7 + +an object by number, 6-6 + + +INDEX + + +remove + +a device driver, 7-4 +rename + +a file or directory, 9-4 + +a process, 10-7 +reset + +I/O cancel request, 8-7 + +I/O Request, 8-7 +reset system + +getting the reason for, 19-2 +resume + +a process, 10-5 +re-vectors + +capturing, 19-9 + +releasing, 19-10 +S$SVER + +environment variable, B-9 +Scan codes + +HC alphabetic, 21-8 + +HC numeric, 21-9 + +Series 3a, 21-8 + +Workabout, 21-9 +seek + +a file to a new position, 8-8 +SegAdjustSize + +adjust the size of a memory segment, 2-6 +SegClose + +close memory segment service, 2-4 +SegCloseLockedOrDevice + +close a locked or device segment, 2-5 +SegCopyFrom + +copy from memory segment service, 2-7 +SegCopyTo + +copyto memory segment service, 2-6 +SegCreate + +create memory segment service, 2-3 +SegDelete + +delete memory segment service, 2-4 +SegFind + +find all segments service, 2-6 +SegFreeMemory + +size of available segmented memory, 2-2 +SegLock + +lock memory segment service, 2-5 +segment + +change size of a memory segment, 2-6 + +close a memory segment, 2-4 + +close locked or device, 2-5 + +copy from a memory segment, 2-7 + +copy to a memory segment, 2-6 + +create a memory segment, 2-3 + +delete a memory segment, 2-4 + +directly accessing, 2-1 + +find all segments, 2-6 + +lock a memory segment, 2-5 + +locking, 2-1 + +names, 2-1 + +size of available segmented memory, 2-2 + +size of a memory segment, 2-5 + +unlock a memory segment, 2-5 +SegOpen + +open memory segment service, 2-4 +SegRamDiskUsed + +size of RAM disk service, 2-7 + + +xiii + + +EPOC O/S SYSTEM SERVICES + + +SegSize + +size of memory segment service, 2-5 +SegUnLock + +unlock memory segment service, 2-5 +semaphores + +creating, 4-1 + +deleting, 4-1 + +signalling once without re-schedule, 4-2 + +signalling more than once, 4-2 + +signalling once, 4-2 + +waiting, 4-1 +SemCreate + +create semaphore service, 4-1 +SemDelete + +delete semaphore, 4-1 +SemSignal + +signal once service, 4-2 +SemSignalMany + +signal many service, 4-2 +SemSignalOnceNoResched + +signal once with no re-schedule, 4-2 +SemWait + +wait on semaphore service, 4-1 +send + +a message, 5-3 + +and get reply asynchronously, 5-4 + +and wait for reply, 5-4 +sense + +an absolute DBF record, 20-9 + +the current DBF record number, 20-13 +shiftstates + +Getting, 8-10 +signal + +a semaphore once without re-schedule, 4-2 + +a semaphore more than once, 4-2 + +a semaphore once, 4-2 + +from the supervisor, 5-5 + +from the supervisor I/O , 8-11 + +1/O completion, 8-5 + +1/O completion by pid with no re-schedule, + +8-5 + +1/O completion by process ID, 8-5 +SignedIntToFloat + +convert signed integer to float service, 14-3 +sine + +float function, 15-3 +size + +a database file, 20-6 + +of addressable systemRAM, 19-6 + +of a memory segment, 2-5 + +of a string, 18-4 + +of systemram, 19-6 +sleep + +a process in system clock ticks, 11-2 + +a process in tenths of a second, 11-2 + +a process till a given time, 11-1 +sound + +cancel playing back file, 8-13 + +cancel recording to file, 8-14 + +getting the flags, 19-7 + +play back file (partial) asynchronously, 8-15 + +play back file asynchronously, 8-12 + +play back file synchronously, 8-12 + +record to file asynchronously, 8-14 + + +record to file synchronously, 8-13 +setting the flags, 19-7 +using the piezo, 19-7 +Sound +Pitch calculating, 19-7 +Sound file names +Series 3a ROM, 8-12 +sound files +format .wve files, 8-1 +SP$DRV +environment variable, B-7 +SP$OPT +environment variable, B-7 +square root +float function, 15-4 +SSD +relog, 21-11 +status +of a device, 9-5 +of a file or directory, 9-4 +of a file system, 9-5 +string +capitalising, 18-1 +comparing, 18-1 +comparing folded, 18-2 +conversion to float, 12-5 +conversion to folded, 18-1 +conversion to integer, 12-3 +conversion to long integer, 12-3 +conversion to unsigned integer, 12-2 +conversion to unsigned long integer, 12-2 +copying, 18-1 +copying folded, 18-1 +length, 18-4 +locating, 18-3 +locating folded, 18-3 +locating in reverse, 18-3 +locating in reverse folded, 18-3 +substring, 18-4 +substring folded, 18-4 +validate, 18-5 +wildcard match, 18-2 +wildcard match folded, 18-2 +StringCapitalise +convert a string to have the first letter +uppercase and the rest lowercase service, +18-1 +StringCompare +comparestrings service, 18-1 +StringCompareFolded +compare strings folded service, 18-2 +StringConvertToFolded +convert string to folded service, 18-1 +StringCopy +copy string service, 18-1 +StringCopyFolded +copy string folded service, 18-1 +StringLength +length of string service, 18-4 +StringLocate +locate a character in string service, 18-3 +StringLocateFolded +locate a character in string folded service, +18-3 + + +StringLocateInReverse +locate a character in a string in reverse +service, 18-3 +StringLocateInReverseFolded +locate a character in string in reverse folded +service, 18-3 +StringMatch +match a wild card string service, 18-2 +StringMatchFolded +match a wild card string folded service, +18-2 +StringSubString +find a substring in a string service, 18-4 +StringSubStringFolded +find a substring in a string folded service, +18-4 +String ValidateName +validate a system name, 18-5 +structures +SupplyInfoEnt, 21-11 +sub- buffer +in a buffer, 17-3 +in a buffer folded, 17-3 +substring +in a string, 18-4 +in a string folded, 18-4 +subtract +floats, 14-2 +suffix +getting text, 19-11 +SupplyInfoEnt +Data structure, 21-10 +structure, 21-11 +suspend +a process, 10-5 +swap +two buffers, 17-1 +switching off +disable/enable if mains present, 19-16 +get state if mains present, 19-16 +switching on +reporting, 19-16 +synchronous +V/O , 8-3 +message reception, 5-3 +tangent +float function, 15-4 +tasks +creating, 10-4 +terminate +a process, 10-6 +termination +registration, 10-6 +text +getting operating system, 19-8 +tick count +sense current, 21-11 +tickle +resetting the autoswitch off timer, 19-15 +TimDateToDaySeconds +convert date to day seconds service, 11-3 +TimDayOfWeek +day of week service, 11-4 + + +INDEX + + +TimDaySecondsToDate +convert day seconds to date service, 11-3 +TimDaySecondsToSystemTime +convert day seconds to system time service, +11-3 +TimDaysInMonth +days in month service, 11-4 +time +convert date to day seconds, 11-3 +convert day seconds to date, 11-3 +convert day seconds to system time, 11-3 +convert the system time to day seconds, +11-3 +getting the system time, 11-2 +setting the system time, 11-2 +sleeping for system clock ticks, 11-2 +sleeping for tenths of a second, 11-2 +waiting till a given time, 11-1 + + +times + +absolute and relative, 11-1 +TimGetSystemTime + +get the system time service, 11-2 +TimNameOfDay + +name of day service, 11-4 +TimNameOfDayAbb + +abbreviated name of day service, 11-5 +TimNameOfMonth + +name of month service, 11-4 +TimNameOfMonthAbb + +abbreviated name of month service, 11-5 +TimSetSystemTime + +set the system time service, 11-2 +TimSleepForTenths + +sleep for tenths of a second service, 11-2 +TimSleepForTicks + + +sleep for system clock ticks service, 11-2 +TimSystemTimeToDaySeconds +convert the system time to day seconds +service, 11-3 +TimWaitAbsolute +wait till a given time service, 11-1 +TimWeekNumber +week number service, 11-5 +trash +a DBF buffer, 20-4 +TW$S +environment variable, B-6 +unload +a dynamic library, 6-2 +unlock +a memory segment, 2-5 +UnsignedIntToFloat +convert unsigned integer to float service, +14-3 +update +a DBF record, 20-11 +validate +a string, 18-5 +vectors +calling, 7-5 +version +of the ROM, 19-1 +operating system, 19-1 +the DBF version number, 20-8 + + +EPOC O/S SYSTEM SERVICES + + +W$C +environment variable, B-7 +W$R +environment variable, B-7 +wait +an I/O completion, 8-4 +an I/O completion no handlers, 8-10 +a process till a given time, 11-1 +a specific I/O completion, 8-4 +on a semaphore, 4-1 +watch +all exits, 10-8 +week +number, 11-5 +wildcard +buffer match, 17-3 +buffer match folded, 17-4 +string match, 18-2 +string match folded, 18-2 +WP$SPEL +environment variable, B-7 +WPS$THES +environment variable, B-7 +write +a DBF descriptive record, 20-8 +a DBF extended header, 20-7 +to a file, 8-8 +to an I/O device, 8-8 +WVE sound files +format, 8-1 + + diff --git a/docs/1-06 Additional System Information 2.00_djvu.txt b/docs/1-06 Additional System Information 2.00_djvu.txt new file mode 100755 index 0000000..2867c06 --- /dev/null +++ b/docs/1-06 Additional System Information 2.00_djvu.txt @@ -0,0 +1,9417 @@ +ADDITIONAL SYSTEM INFORMATION + + +Version 2.00 + + +December 21, 1993 + + +(C) Copyright Psion PLC 1990-93 + + +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 and +Psion Series 3a are trademarks of Psion PLC. | + + +TopSpeed is a registered trademark of Clarion Software Corporation. M, 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 +A IVICUINK: MICDIINt;-GNG SNK vcsissscssccasncscdececeu cease ovcenveuieve css ecueedudciiessneidcrecdeewencs 1 +VIGIIIIKOXG yccecuscccasasacezediwaanerew nodes seaatani oes ousescaiencannandessaaevdocancautesecseeises 1 +Commands provided in MCLINK..............ceccccscccscccccscccccccscscccccsscssecccees 1 +MCLINK and single floppy disk drive PCS ..............ccccccccssccsccscccscccceccess 2 +Exiting the MCLINK program ............ccccccccccccccscescccsscccsccesscccessovesecccees 2 +Display the version Of MCLINK ..............ccccccccsccescccvccccceccsseenccsesssceccers 2 +MCLINK file-handling Commands. ............cscccccccscsccscsscsscssccscesccscscccecesccececs 2 +HUIGS ON: TIEMAMES 5 suisse eevesseecoradisbicai conc ceeaiebiededanssacatesadentesescieneeeek 2 +NLR cerca oc ewemiocsnt acto ance Neate saw ce dea mane naka welde ona anteducumcedsauaicecieielse ont benceaees 3 +COPY aaiiadteiicatiaiencae lunes cso cs Monnens sonee arctan naneeaten age iannend awe a 3 +RENAME coscinececead cs eae tenscvwvscsesuiaincadse utaeoet Solanueswaesaaneoue nae ees 4 +EE iE acces itcacidio ae swetaetaontaddaenwasoeias ces cee ueanten semaalen sanubaw Mie cenGee leas eeeees 4 +BVI DUR eo tessastcicoacaing eatavenadeaceu ee uncanaie suse pademnacea chan aaoneeaceeere ceed eects 4 +Changing MCLINK communications SettingS..............ccccccscscscscscscccscscsecececs 4 +Options for the SET Command ...............ccccscccccccsscccssccscesccccceccceccceccecs 4 +Serial port and Baud rate Options ............c.cccccccsscssccscccsccscccccecccecccsececs 5 +MIOGEM OPTIONS hsiscssceseshaec cant dav sencasvs cous autacadecuaevedeisantatenias eoeeeeeiedates 5 +Examples of the SET command +Advanced use Of MCLINK.............c.cccscccccscceccccnccssscsescccsssseccvessecsvecevccencs 5 +Running programs remotely on the MC, HC or Series 3............cccccccsecccs 5 +MICLINK batch files ...............cccccccscccscsccccssccccscsssscecceccsccsssceecseccsveecess 6 +MCLINK command line processing..............ccccscscsssccscsccsccccecsccscecescecess 6 +Invoking MCLINK inside an MS-DOS batch file .................cccccsccecsccscceces 6 +MICLINK and MOdeMS .............ccccccccccsccscscsccsccsccsceccsccecescccecescescevecesescccess 6 +MCLINK as a PC file server via the phone System. ............scccccccsceccesscces 7 +MCLINK and modem Baud ratesS.............cccccccccscsccsccccesccccscccesccccccssecess 7 +Link on the MC/HC as a requestor via MOdEM.............sccsccsccscecscescecccces 7 +Link and Modem Baud rates. ............ccesscccsscccsccscessccecceesccesceccseves ere 8 +Link/MCLINK with MNP ..............cccscscscsccscsccsccssscsccsctecessescsceescscescesces 8 +Examples with modems. ............cccccccccsscssecsccccccscsscsscescceccceeccecceccecsesecccecs 8 +Using a Dacom QuadPlus MNP 5 compressing modem...............scecceseees 8 +Using an Amstrad SM2400 moder. .............ccececessccssescesssccccscsccccecceccs 8 +Using a Dowty Quattro SB2422...............cccccsccccsnccsccssccccccececcccccvecccess 9 +Using a WorldPort 1200 pocket Modem. ...........ccssceccccsccecccccscccscceccccecs 9 +An HC with a Psion Quad modem ..............sccscscscecccccccceccccccccccececccecees 9 +An HC with the Amstrad SM2400 modem ...............ccsccsccscecccceccecceccecs 9 +IVIGDEING- OXG se scecsressiacecaassewcineroiswateastcusssaousaseecate ain eeGaigontanmuceteadaventienat: 9 +USING -MICPRINE vvtauisscomadccsuacrencoss sean wdasanseceeutaonuseeataedia ake coveuumeewad 9 +EXITING MICPRING 25 cevscecasccancsdesctus boveareviccets eeceanuiedosstantdea ndencecatannecins 9 +Printer Configuration On the MC ..............cccccccsccscscccccesccsccsccccesccscceecces 10 +Printer configuration On the Series 3............ccccecsccscsccecccacsssccsccscescceaces 10 +PAlAMPELOIS 5.0555 cds ccccae saeuaaenwse caw tasson sense wale dese omer ueceessc2 seven aieawed vacation suiek 10 +The parameter .............cccccsccscccsccccsccsscccceccceseccccuceececesevucess 10 +The -C parameter .............cccccccccccscccsccsccsccnccessctsccsceccccececeucess 10 +The -t parameter.............cccccccccccccsccssccccccccccesceccceccecescceecss 11 +ENG = DAFAMEER oii coescs teins acacnsicsewrvecsnssidalsceobicasctwuduesdecewesleisaesececetors 11 +SHIA O XC esis ieeeend arcs oceciidastavcbated dbaeetiubaes een eoedaaceeenveuki cate weduGlasaaieadacecs 11 +A RESOUCE FUCS vce oa casters csoens a dunciscnntedavauaaspuesxdaauianSnesadneswaniieasWenieapentteaewenedonecs 13 +MICFOGUGTION iescesecaie awossse eects odale ices watcsaacassnsRacbensantes vecsaue usa Oeaecied aeseewenas 13 + + +ADDITIONAL SYSTEM INFORMATION + + +rr reser ssh se ress nna eremmeeee + + +Format of Sibo resource fileS.............cccsccecenccccccccccccs : + + +isiehuce na aeeecaadecusnaidmsseate 15 +The format Of .rsc fil€S............cccccsseccsecessccesceeces | Sesh aeiiniaanastaesasee cia 15 +Some strategies for reading .rSc fileS..............scccsseccecsscscscececscscscscsasess 15 +Example of reading resource files directly............. hehe wedencuvmeuaciatewsinues 16 +Using the rscfile Class in Olib..............:sccccsecccscscccscecscecccscscsceceseccscssccseeees 16 +Basic services of the rscfile claSs..............cseceseees | atoatealeiactecie See teatmt aati 16 +Reading compressed resource files with the rscfile Class .............ccceceeees 17 +Initialising an rscfile ODjeCt.............ccccseesecsecscseees Pere ree ree 17 +Which header files are needed ................cccceccecccsceccccssccsscsccscescccccsceees 18 +Run-time errors with the rscfile ClaSs.............ccccccdecssceccescsessscsccsscnsceccs 18 +Possible errors during initialisation ...............cccccccqcscccssccsscsecsccsaccessenccs 18 +Errors during rs_read Or rs read DUf............cscsscscdscsecscecetescsscnssceseecaes 18 +How rscfile errors are reported .............cscesseseeeees d eusigulee se sa beamquabeeua sears 19 +Dealing with errors in rs_read or rs read Duf.............c.ccscscscssscncnceesceees 19 +Advice on where to locate resource fileS ...............ccccdecescccccccccccccccssecccccecs 21 +Mono-lingual applications ..............cccessccccescccvssccdescccccccccccescsccccscceececs 21 +Multi-lingual applications ...............ccccccncccccccccesncsecccccccsaccecsssssccscecesess 21 +Copying of applications ...............cccccccesscccssceeccess Siicatacsaronteee eres 22 +General comments on multi-lingual applications..............csccccsscsssesscccscesceecs 22 +The basic principle of independence of code from resource file .............. 22 +Careful design of screen layout ...........cccccccessccccccercccscceccceccsccesccecsences 23 +Codesize problems. ...........sscsscsscssssscsscscscscoesenees shorty Dating TectatSoeectacan: 23 +Varying KEVYDOAlGS viessisciside cake tices ened ice dikcwks aidesecdeceseedoxwca veweuceieens 23 +CONCIUSION aise Sec cctyatiwreestcocascsiice soi uadotessiadononeseeke UL cbaduadingniemaeeeea mannan: 23 +Creating .rsc files USING FCOMP.EXE...........ccecccccsceeesecs i alerhcsaseianaieta bse alesis aia oleeecies 23 +GONGFateG