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 <add eos tatetee ethane 2-5 
The need to flush the Window Server buffer .............eeeeseeesseeeeeeeseesseesseeseeeeneeeees 2-6 
Other graphics calls in Gauge........ eee eeseseessseeesseeesseeceseecneeceseeeesaeecsaeessseeseeeseeeeses 2-6 
A suite of line editor fUNCtIONS........ ee eee ceseceseeeeteceteeeesaeeesaeecsseecseeseeceseeeesaeeesaeers 2-6 
Full specification of the lined fUNCtions 00.0.0... eee eeeeeeeeeeeeeneeceseeceeesaeecsseessseeesteeeesaes 2-8 
General: COMMENTS. c5k satis eee eh eaves eu aati wink ara ates 2-9 
Device: drivers for the HG os. sescccschgeseceges sents ce eSceass etka eet ates stesedeed cutest nts echeebeet teases 2-9 
Writing a customised shell process ............s:ceescccsseccesseeceecesseeesseecsscecssceseeeseeeesaeeesaes 2-9 


Developing applications on restricted-keyboard HCS ..........seseeeseeesereeeeneeeeneeseneeeeee 2-9 


GENERAL PROGRAMMING MANUAL 


3 HC Command Sheell..............sssscssssscrsscrssesessssessesssesssesssesssessessssssssesssssssesesessesssessseessssseeeseees 3-1 
OVERVIEW oe thee alah ot Bi, SE SS EE ets 3-1 
Batch file processiie? iss..5tsess 3 ciisuhitiev A ashektaid iinieie a stigs Auslasoaies debs easdabiense die oeses 3-1 
Launchin® prosrams iis. tccee pt ital chs eed i eae tered oe teens meats 3-1 
Synchronous programs and asynchronous Program ...........csecceseceesseeeeneecsneeeeneeeesaee 3-2 
"Fermin atime Prosrawnss : ja: ces.se.cseeesdahees: sees sev edhesehe beet edeede seth sdutedevedes ents eaubedeyege eats odes 3-2 
The command line editor... eee eeeeeesecsscecsseeceseeeesseecsseecsseecseesesseecsaeesseeesseeensaes 3-3 
Pausin & the Screen display +. c.2i0: .oagetsne teste aun estes aie la A 3-3 
Additional copies of the Command Shell oo... ee eeeeeceseecsneeeeseeeesaeecsaeessaeeseneeeeee 3-3 
Sending commands from a remote PC .0........eeeeeeesecesseecsneeseeeceseecesaeessacesseeeseeeesaes 3-3 
More on running programs remotely «00.0.0... -cesecesseeessseecscesececeseeeesaeecsaeesseeesneeeesaes 3-4 
Auto-terminating and non-auto-terminating Command Shells.......... ces ceeeeeeeeeeeeeeeeee 3-4 
Bilés:and :diféctories:..2.cc2iteaiesestirratascav als nie cee anton eave os 3-4 
File Th Use serror,iMeSSages: 2. 2ce: sce suetesleaeete deg eeteckp sucks cep edehodvecusbecesadetsatesaebedepode gents ov 3-4 
Default path and current GirectOry 00... eeeeeeseeceseeeeseecsseecseeceseecesaeeceseesseessneeeesaes 3-5 
Specifying file names as command parameteTS ............ cc eeeeeeeeseceeneeceeeeeeeseseeseneeeesaes 3-5 
More details on filename specifications ...........eeeceeeeeeeeseessseeseseecsseecesaeecsaeessaeesseeenes 3-6 
Specifying paths as command parameterS...........eeeceeseccsseeceseeeesseecsseesscessneeeeseeeesaes 3-6 
The requirements of generality... eee eeseecsseeceseeeeseeecsseecsseeceteeeesaeecsaeersaeessneeeesaes 3-6 
Alphabetical Mstitie:.d.c 3 ec ctti tee, led Bed a ie eta sa et Bat se tn ae eto 3-7 
NO tation 2:3322.545; eke satin ea Bishi weenie eh ee 3-7 
How commands are implemented .............eeseeeseceseecsseeceseeeesaeeesseecsaeessaeessseeessaeeesaes 3-7 
Set or clear file attributes (ATTRIBUTE) .0...........cccccccccccccesssssseeeeeeeeesessseeeeeeeeeeseenaaee 3-7 
Set time to auto-switch-off (AUTO)..........cccccccsssscccccceeessssseeeeeeeessesseeeeeeeeessessaeeeees 3-7 
Set backlight time-out (BACKLIGHT) ...........ececcceeesccceeseneeeeeeeeeeeeeeneeeeessneeeeesnneeeees 3-8 
Start battery check program (BATCH )...........ccceescsssecceseessseeceseeeesseessaeessaeeesseeensaes 3-8 
Specify battery type (BATTERY) .........ceeeeceesscccsseecsseecsseecesaeeesneecsaeecseeesseesesaeessaeers 3-8 
Change directory: (CD). 27.3 vc Sie eS aseitoes sates ste nssng cok cbvstotes Wag ak Uovssoteestngeds Gustaaee staged eae 3-9 
Set language file (CONFIG) ....... ee eeseeeseecssceceseeceseeeesseecsaeecseecsseeessaeeesaeessaeeseseeeees 3-9 
Copy file(s).(COPY,)..cdincccteuiiscosatededegedess cosated odetavtstcetated odegudigreunsdegedesadssoeeneded odagoeeons 3-9 
Brief directory listing (D) sicc0.scctsgpsesteeeses Siete deceytews eyes bedivbest dope eandelcspeeiaeding 3-10 
Display date and time (DATE) ......... ees eeseeeeseecsseeceseeeseeeeseeeesneecsseecsseesseesseeeesaeeesas 3-10 
Delete file(s) (DELETE) s.ces.c0 cienitescatais ni eiieiasar aueiigiie: dieerae era 3-10 
Last devices’ (DE VICE) ssssc ove; ccessegedesevss sues sesedes covesect sins oles saee sues sans oteh Secsbuns shea dekeuss sie 3-10 
Full directory listing (DIR).............cs:ceseseessseesenesenscnensenesonesseeeeessenesentensedonesenessenenees 3-11 
Display or set environment variable (ENV) ..........::sssccsesecsseeeneeceneecsseeceseeeesaeeseeeesaes 3-11 
Bxit level (EXIT) 3s. sates ataie nisin casei: theres evaeed aiaraieiohls 3-11 
Format device (FORMAT) ...........cccssscccccccessessseeeeeeecessesnseeeeeeceeseesseeeseceeesesssaeeeeeeeenes 3-11 
Display free memory (FREE) -.:.0..3:.:e.:ecesseeecensesdesevevesdenssobesancesesdenevebtsaboesvedepisateseted 3-12 
Kall ai process: (RM) :oeccue cectees sn. Se voeachatees sen cdesta sia seieds Saeuteteat ick ces duct etivtastece aucuteetes 3-12 
List :device drivers (LDEV.) sivsccs.seveccsncvaeccsesesvcesucceeccovsvancciecces cess sxaudcseevesesasceencedevesvees 3-12 
Start Link program (LINK) .............::..::ccseseesssevensetensetenener sesenensetenseessoneoensenenseteneee ss 3-13 
Configure low battery warnings (LOWBAT) .........eeseeesceseeeeneeseeecsseeceseeeeseeeseeeesaes 3-13 
Last:processes: (EPROGE) vite sex. chses seca tedeaesd ie azeadeeech Vacetegesstetsandevekeancteeats caevsedactautede cote 3-14 
List: segments (LSEG).0...c3.ecceediesvasccsevsauscaestescesesuatceavscnacens senucenvecnecescesuceavedeaseseedeees 3-14 
Display time/date of mastering (MASTER) ..........:-eesccesseecsseeeesseecsneeseseeceseeeesaeessaeers 3-15 
Make: directory (MD) sc.cicsicseeccecsiesti eves ti desieanscavssanacendsancduvacetecuvdcan cdevscabedevacancdevecsoees 3-15 
Control whether the Notifier appears (NOTIFY)..........:.esscessscesseeseeeceneecsneeeeseeeeseeens 3-15 
Enable off-key handling (OFFENABLE) .............eesceeseseseessseeceseeeesseeesaeecsaeessseeeesaes 3-15 
Remove directory (RD) ..........::cccesessccesssceeeeeeneeeceeeeeeceeneeecssnaeeecseaeeeeeseaeeeseeneeeeeeneeeess 3-15 
Rename file(s) (RENAME .)................ccsessscccccesssssscceccecsssensnsseeccessssnsnasseeceessssssnseeeees 3-16 
Resume a suspended process (RESUME )..........:.:ssscssseessscecsseeceseeeesaeessaeecsaeessneaeensaes 3-16 
Set default path (SET) cccsccvccssccssesas code cueascaecsaacess cans ceccaacebscdauctevecaavenscdaasssucddeeeat cdanes 3-16 
Set time and date (SETDATE) ............c:cccccccssssssccceeeceeseneeeeeceessesseeeeeeeeeseeeeeeeeeeseeeaaea 3-16 
Suspend a process (SUSPEND) .........eecceeseecesseessseeesseeceseeceseeeesaeecsaeecseeseseeeesaeeesaeers 3-17 
Terminate a process (TERMINATE) ............:::cccsssscceeeeneeeeeneeeeeeneeeeeenaeeeceenneeeeneeeeeneas 3-17 
Type a.text file: (TYPE) sccscccvccseteaeccatccusvecsecenscees cose cca vecauacssevaecavvesanscaecvaa ceveiaenceseccanes 3-17 
Display software version number (VERSION) ...........::ccsccceseeceseeeesseessneeceeecsaeeseneeeees 3-17 
Wait for a process to complete (WAIT)... eeceeeseeesneecsnecseecseecsseeeesaeeesaeecstessaeers 3-17 
Configure Notifier appearance (WNOTIPFY)...........esecesseeceseceseeeeseeceeesseesesereneeeees 3-18 
What happens when the Command Shell starts .......... ec eeeeeesseeeesneeeeneeseeceaeecseeseseeeesaes 3-18 
When no command line is passed .........eeseeseccesceceseeeesseecsseecsseecsseecesaeessaeessaeesseeeees 3-18 


ii 


CONTENTS 


4 The HC in the Cradle.............sccsssssssssssscssssssesssessscsssssssesssessscsescessesssessscssscsssesssesssesssessseesors 4-1 
TMtROGUCH ON sei iecen sie ceectuvedebaveescenedivaceeadivebenaviyedetadie svete ssena tia suenbdin suctarda seuaecer sucka deasuuseres 4-1 
POLE Coecde egies Bebe 8 FRG eect wee ae eUEEOAa ea Lae d baa bak andgn odd ee oo een dane de eae evatenddan te sebens 4-1 
Hardware: CONNECHONS®. .xe.b.s ckciied cxsebbedens eect ati eNead eee aeietled Goethe lad eset head Coe cack 4-1 
Fitting an ASIC-2 expansion card .0.......ceeeeesccceseeceseeeseecescesseeceseeeesaeeesaeessaeesseeeees 4-1 
Software COMNECTIONS...........::ccceeeseceeeeseeeeceeeeeeeseeeeceseaeecceenaeeeseeaeeeceeeaeeeesenaeeecesnteeeeteaeeeens 4-2 
High speed remote file access using Link software.............cccsscceeeesseeeeeseeeeeeeneeeeeeeeees 4-2 
High speed debugging using Link software.......... ee eeseceseeceneeeeeeeeeseeeesaeeseaeeseeeeees 4-3 
The PMX/HSS mechanism. ...........:.cccccssscccesseceecesneceeeeesneecsesnececeeneeecssaeeeeeesaeeeseusnseeeseanees 4-3 
Conf suring HSSranniSys ccseee ty odeusss pesut etsy oces sat Codat dep osessteg sant ePesecoshtes nxt esseuanpotaderty ees 4-3 
The PMX? device driver :..:scccccsccsecevsganedevsectviesvechadestedeadenn(dnadesbedesuvabideveeabedevisarcconaees 4-4 
More details about PMX...........ccsccccesssscceeesnceeeeeseeeecesneeeeeesaeeeesseaeeeseseeeeeensneeeeeseeeeees 4-4 
The CRD device driver si.cciccccsies ee ticdeveesceiertevccdeaces cetesdavcess seaucesvedaecedeaces ceavedebeeneeeasctanatea 4-5 
5 Customising the HC ROM...............sssccsscssscssssscscsscssecssscscecssscscessssesessscsscssesssscsecssssesesssscsessseees 5-1 
ThitrOductioniess eee eceaes od save Missin sce asaesdevnacesceasscasvandecseasdcheduasaducseas sideavaaciasdeasndeetuaneess 5-1 
Some cautionary TEMArKS \y  sa.: chs ois cavscenscvhe dete stuylones dude cays cuvicshs del Sevescuydcavaseh sevsewvbobed 5-1 
Creatin gran HC master files. ::ssieitsicssteetactas toadoacteaien euosieitesenetaaioietiseed Mlaatecabeatieestias 5-2 
Invokin sseroms, 3 ssi Biel ha hell ia hake austen aetna 5-2 
Malad version MUIMDeLs, sii. i555 sis ceessidagedes ceandaea desssueacessacea suas seas casncdeasves sta cosvedsadeaactacses 5-3 
The files comprising the rOm...........ceesecesseecesseecsseeesseecsseecssaeeesaeecsaeecsseeseneeeesaeessaeers 5-3 
SiZe@ COMSIMEPAL ONS iscsi 55.50 as. shed svedencs ance las veucbtcaii ace ids wae caacatnaee sea eae ebeegnaeeaseaeaeeesaseorasaseatens 5-4 
Some possibilities for CUStOMISATION ...........eeeeeeeeceseeeseeesseecsseecececesaeeesaeecsaeesseesenaeeenaes 5-4 
An alternative Shells visi liveseiealssetavaesiscceavecesartasetseeas dec misrsetaciarstesnsusiieaenactesnaneitaaes 5-4 
Vatrant Conf s Tiles 2... 2. scigseesi cus Sens eeseeub Subs tenssistaves fers cevssmpncihe ivsexuseupseciefeaceusenvseibeds 5-5 
Additional files that might be added ooo... ee eee eeseeeeseeceseeeeeeeeesaeecsaeesseessneeesseeeesaes 5-5 
Files that might be omitted ..................cce:cssessessereneeteneetesonessoneessevesenensoneosesesesenenees 5-5 
Customising the Window Serve ..........::cescccsssseesseecsseeceseecesaeeesaeecsaeecsneecsneeeesaeessaeers 5-5 
Creating and using a master SSD ooo... eee eeeeeeseeceseeesseecsscecssceceseecesaeeesaeecsaeesseeesseeeesaes 5-6 
More details on master SSDS............:::cceesesceeeeeceeeeeeeeeceeneeeeeseneeeeeseaeeecsenaeeeeeeneeeeeeeas 5-6 
To repro numeric keyboard HCS ...........cccecccceesssceeeeeceeceeenceceesceeeeseeeeceeneeeeeenneeeeneas 5-6 
Files:requatedy., secs. s2ievsussceawbust sates cide ceuctecssoacet cusnastc cesasakacesecdka casuaats tesucdas deaptesauvactze sages 5-7 
Appendix A: Technical Specifications.................ccscscsccsssscscssscscseecsscseesssscsessssssesssscseesssssessseees A-1 
Psion Solid State Disks Technical Specification .........:cccccccceccecceseteeeseeseessensensees A-1 
Psion HC Technical Specification r.........cecccccceceecceseesseesceseeseesseeceeseeseeseeeeeeseeeeneeneeees A-3 
Psion HC RS232/Parallel (printer) module version 1, Technical Specification................. A-4 
Psion HC RS232/Parallel (printer) module, version 2, Technical Specification................ A-5 
Psion 15 Way to 25 Way converter cable, Technical Specification ...........eceeeeeeeseeeeneees A-7 
Psion HC MCR /RS232 /TTL RS232 module, (Version 2), Technical Specification ........ A-9 
MGR ANtertace «orcs ck. ceccevcd dace heetate re cotevederngaaddeteties dodaserePeiatedeeadage des edtsedeesdcseeaestes A-9 
RS232-/-RS232 TTL mterface . :cicec.ccssiean arith vienna eid A-9 
Psion HC RS232/TTL RS232 Interface Technical Specification ............ ec eeeeeeeseeereeeeneees A-10 
RS232 interface. vccscccesvacevccgnccasceauacoecedecaveeeanaea cesaa seveesanccdh dual ceveisencdsscaa cesvieanceeuccaacess A-11 
RS23 2:7 TL) interface ocecd seed cee cetescvecedue ec bignees odtatedesbindevaeiuntecssndasedednins eBeasdinevedzentstes A-12 
Psion HC 16550 RS232/TTL RS232 moduleTechnical Specification ...........ceeeeeeeeereees A-12 
RS232aniterfaGe ices tee kei eeseese acct oan Ata ER eset as ha eee eee aah event act feed A-13 
RS232 TTL, interface sv.cis cccscaiacdescaasiecaeideceedeaecvevandeacestadeaecsaaceveiadracsvicanedessedacensceaavens A-14 
Psion HC Bar Code Reader module, (Version 2), Technical Specification ...............:0 A-15 
Psion HC RS232 / Bar Code Reader module, Technical Specification........... A-16 
RS23 25M terface iicstecs oh casei each exes eR A ke ih aah cacao ing eee Soe eee eed A-16 
Bar Code interface: si; cesseciecesnceiiecataeecccancdegevauacesesanadenduanceve cies deveisancagecaa cevvicanceeccaacees A-17 
Psion HC Modem UK module, Technical Specification .........cccccccececeseseeeeees A-18 
Psion HC Vehicle Interface Box Technical Specification ......... ce eeseesseeeeseeeeseeeeeeeeeneers A-19 
Psion HC Cradle Technical Specification ..........cccccccecceccesseeseeseeseeeeeseneeeseeneeneeesees A-20 
Psion HC Docking Station Technical Specification ...........ceeeeeeeesseeesseeceseeceseeeesaeeesaeers A-21 
TtrOductt On 4.02. cscs ives ctscceecotegerteotserneetteeas dutusivcnodetevegelnterdeaintadededs sativa dibetedadassveviadeetes A-21 
Compatibility with Psion HC and RWAN machines 2.0.0.0... eeeeeseeceereeeeneeeeeeseeeeeee A-21 


iii 


GENERAL PROGRAMMING MANUAL 


iv 


Compatibility with the Psion HC ...........cesceeseeceseeceseessseecseeesneecsacecseeceseeeeseeenaeessaes A-21 
Compatibility with RWAN/PDT220 0.0... eeecccsseecesneecsneeceeeesaeecsaeecsseeceeesesaeenaeeesaes A-21 
VARVAMS © osc Sautsrsh eehioed Sant rock Penh cob dncn cu vdesuh ideSbiacbs cevbeses sebulocbonvigedecesoecusseh cevbeneiscbhacevese A-21 
Identifications. scsis. 4 stcbistetets sohevisesadased, Pedaphistepspteas ap esaphenensvdiseecuphehlsieuebeseey hs A-22 
Fast-Chat ger: init, 2.5 cers ai cesch cov cha ssubstins rela chuscouesadinsrove Guasus suns pac sduscbeasebaduossuvadeessteres A-22 
Main features, 3 cseiztioset isis suncalsevesashesiarsasdnidouet sstereapsenasthoastaaiaesanactapestoataauoauestanteass A-22 
SfAatUS-IMGICALOLS F555 552555 leaded cash heat ion inches Sogeh Gouh dea buts veveceeires ended ges deensecdaseboubeessaeeh sea A-22 
Battery: Chargin Siu ccstlcctiasscechinssvatesngess duvtiies fesncicsovage qwiee dotediescsuedees peassasduasaiebeteceateas A-22 
Battery Status LED Conditions.......... ees ceesceeeseeceseceseeeeseeeesaeeesaeecsacecseecsaeesseesesaeeesaes A-23 
Charsing both battery packs..ciisctisicc.veesiosdonstesiacsesiaskgsncastediadeanigisosstegssteuvieudaeseanetta A-23 
Battery Fast Charging Conditions............ccccesscssssesseessseeceseeceseeeesaeesneecsaeessaeessneeeesaes A-23 
Disharging prior to charging & capacity MeaSUFEMENE ......... eee eeeeeeteeesteteteeteteeeeee A-23 
CHar sine times ieee ercies sctsasees Ssceesccbs tes teks cots tebacths sub febe estivssts sBuohcoig Sebacubaed sPuvesunscbvasizds A-23 
Ghar sing times’ iis:icse iiss suciilece isis steanietiaieleseteaadias iboesteaseaaniaseitemiaageandiee teas A-24 
Char sing limitations. sis osiecss heist ch bok oeeic ced ide onble sees teeth oceigehks basen aed A-24 
LIF Mounting Kitis ciaandik Anis anise died Amie Anbedanate sae deaee A-24 
HC/HC-DOS Holster with Socket Housing ...........ceeseeeseecsseeeeseecsseessneeeeseeeesaeeesaeers A-24 
HG DochkinS:S tations: ice.tisysse.aeshee tia vkgis douetd ates sas lassetdatcestentase tha eanigaiarethaeasase A-24 
12V 2 amp unregulated Power Supply.........eeeeeeeceescecsseecesseeeeseecseesseeeceseeeesaeeesaeers A-25 
Psion LIF - RS232 Cable Technical Specification... ceseeseccsseecesneeesneeseneeseseeeeseeeesaes A-26 
Psion LIF Connector Technical Specification .........cccesecesseeesseecsseeceseeceseeeesaeessaeesseeeee A-27 
Pin Definition for LIF - PFS Connector ........ee ec eeeeeseecsseeceseeeesseecseecseecsseeeesaeessaeers A-28 
Pin Definition for LIF - RS232 Connector .0...... ees ceeseeeeseeceseeesneecseecsneeceseeeesaeeesaeers A-29 
Definitions 2:2). osst vise tar isis ssid Marhiak bso assee thick sedis neiest as ieiasdenp bos cnsvoiaoseeeoaeses A-29 
NOG sss ee0sacbsied saves cage Beeeed Sauus cots duis ad daet evd ube ded seuee eevbaibedel saves revaaieesed suawssesataveeed seebees A-29 
Appendix B: Safety and Emissions Approvals ................sscscsscsssscsssscsssscsssssssssscsssscsssesscsssssessones B-1 
Safety and emissions technical terms explained ........... ee eeeeesseeesneeeeseeeeeeeeesaeessaeessneeeees B-1 


CHAPTER 1 


INTRODUCTION TO THE HC 


The HC concept 


Combining modular hardware design and the most modern software techniques, the Psion HC range of 
computers represents a new approach to computing in the field. HC computers can extend existing 
computer networks away from the office, right up to the "front line" - whether that's in a warehouse, on a 
sales call, on a maintenance visit, or wherever. Rugged and powerful, HC computers are the mobile 
elements of a computer system, ensuring that information held "at base" in the office is timely and 
accurate by putting the base directly in touch with the point of action. 


The HC has been designed to be integrated into any computer system and to meet any application 
requirement: assisting with the making of deliveries, taking of orders, collecting or distributing 
information, servicing equipment, and so on. 


Every element of the hardware is configurable, from the plug-in megabyte-sized Solid State Disks, to the 
internal expansion slots for peripheral devices such as bar code scanners, modems, and magnetic card 
readers. 


Equally important is the multi-tasking operating system with full graphics and windowing capability. 
Applications can make productive use of the various fonts and emphases available, and can even display 
and manipulate diagrams, maps, and pictures. The result: software applications that are highly 
informative and intuitive to use, and which consequently improve operator acceptance and efficiency. 


The multi-tasking facilities - unique to the HC range among handheld computers - significantly shorten 
software development times and greatly simplify otherwise complex issues ranging from the simultaneous 
monitoring of several peripherals - a bar code scanner and a modem, for example - through to 
sophisticated process control applications. 


Switching on and off 


The HC can be switched on or off by means of the ON/OFF key near the top left corner of its front face. 
Typically, this key is salmon-coloured - though colour configuration is one of many customisation 
measures possible for the HC. 


There is no need to "exit" programs before switching the HC off. When the HC is next switched on, all 
current programs continue from their previous state. The contents of the internal RAM memory are 
preserved throughout the period of being switched off, without any significant current being drawn in the 
meantime. 


Switching on for the first time 
The first time an HC is switched on or immediately following a reset, it will probably display the "Jnsert 
Pack and press enter" message. 


This indicates that the HC is searching for a configuration file called autoexec. btf. 


To by-pass this message and hence accept the default configuration, press PSION+ESC (the PSION key has 
the familiar "cup and saucer" logo: it is usually located near the bottom left of the keyboard). For 
keyboards that do not have an ESC key, SHIFT+C should be typed instead. 


The HC in due course presents a $ prompt to indicate that its Command Shell is ready to receive 
commands. 


HC PROGRAMMING GUIDE 


The basic hardware 


All aspects of the hardware of the HC have been designed with the following goals in mind: 
e portability 

e ruggedness 

e data security 

e ease of use 

e adaptability 

e long battery life. 


Processor 


The HC has an industry standard 80C86-compatible 16-bit processor, the NEC V30H, that runs at a clock 
rate of 3.84MHz. 


The HC also contains a number of proprietary-designed custom-built chips called ASICs, which are 
responsible for many of its more exclusive features. See the Hardware Reference manual for more details. 


Internal memory 


The amount of internal RAM memory on an HC varies from model to model. The basic model, the 
HC100, has 128k of RAM; the HC110 has 256k, and the HC120 has 512k. 


All models have 256k internal Flash ROM. Because the ROM is Flash rather than "OTP" (one-time 
programmable) or "masked", it is possible for its contents to be altered by special techniques, facilitating 
additional ROM-based customisation - even down to the level of individual HCs. 


Solid state disks (SSDs) 


The standard HC has two solid state disk drives, which are the equivalent of disk drives on a PC. To 
access them, open the rear cover by pressing the catch on the left side of the HC (if the catch is locked, 
turn it through 180°.) SSDs can be inserted into the disk drives in the top third and the bottom third of the 
area enclosed by the cover. 


SSDs should be inserted with their upper faces (containing large writing) nearest to the rear cover of the 
HC. 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. 


The SSD drive near the top of the HC is drive A:, and that near the bottom is drive B:. 


SSDs give open-ended capacity for data storage in a highly secure and compact form. SSDs can also be 
read by other computers in the SIBO range, as well as by PCs equipped with an SSD drive. 


The speed of data transfer to and from SSDs is enormously faster than with floppy disks, and compares 
favourably, at 320 kBytes/sec, with even the fastest of hard disks. 


There are no moving parts in any SSD, nor in any SSD drive. This is one reason why, notwithstanding the 
high performance statistics for SSD data transfer, HC batteries last for as long as they do. 


Note that you should never open the rear cover of the HC while any SSD is being accessed by the HC. 
Opening the rear cover switches the machine off immediately, and data loss could occur. In any case of 
doubt, switch the HC off manually (use the ON/OFF key) before opening the rear cover: this method of 
powering down the HC is guaranteed not to lose any data between the HC and its SSDs. 


Types of SSD 
There are two types of SSD: Flash and Ram. Either type of SSD can be used in either HC drive. 


RAM SSDs can be overwritten selectively making them ideal for storing frequently altered information. 


RAM SSDs when not pugged into an HC require a backup battery to preserve their data. The battery is a 
standard miniature lithium cell, with a guaranteed in-use life of one year. It is easily replaced by the user. 


A RAM SSD when plugged into an HC will preserve its data indefinitely; the one year battery lifetime 
refers only to periods in which the SSD is not plugged into an HC - only then does a RAM SSD draw 
current from its own battery. 


1-2 


1 INTRODUCTION TO THE HC 


Flash SSDs are a highly secure medium requiring no battery to maintain data integrity. They are ideal for 
storing data not intended for frequent editing or revision. 


When files on a Flash SSD are deleted or modified the original data is simply marked as "inaccessible". 
The result is rather like crossing out entries in a filofax: the entries still occupy physical space. In due 
course, the disk may become full up with out-of-date entries. However a Flash SSD can easily be reset to 
its original pristine state by "formatting" it. If a Flash SSD is full because unwanted "erased" files are still 
occupying space, but the disk also contains some data still wanted, copy all files to another disk (using eg 
the copy *.* command of the Command Shell). The erased files are ignored by any such copy command, 
so only the data wanted is copied across. The original disk can then be cleared, by formatting it, before 
relevant files are copied back on to it. 


At the time of writing, Flash SSDs are available up to 2 Mbyte in size and Ram SSDs up to 1 Mbyte. By 
the time you read this, Flash SSDs up to 8 Mbyte in size may be available. 


Each SSD has a switch so that the data on it can be write-protected. While an SSD is write-protected: 
e nothing it contains can be altered or deleted 

e the data held on it can only be read. 

The write-protection can be removed by setting the switch back to the 'Write' position. 


Expansion modules 


There is an expansion port at either end of the HC. These can hold a wide variety of interface devices. 
Possibilities include: 


e RS232/parallel printer port 

e barcode reader (complete with wand or CCD/Laser scanner) 

e magnetic card reader ("MCR") 

¢ modem 

e "combination" devices such as RS232/MCR/scanner. 

The two ports are identical, except for their names: "Port A" (at the top end of the HC) and "Port B". 


To remove a module from either expansion port, release the rear cover, in the same way as for the SSDs. 

Slide the release button next to the module to the UNLOCK position and pull the module out. To replace, 
push the module right in and lock the module into position by pushing the catch into the locked position. 
The rear cover cannot be closed unless this catch has been set to LOCK. 


It is even possible for the contents of an expansion module to be exchanged "in the field". There is no 
need to reset the HC before doing this. 


The Fast Serial port and the Cradle 


The Psion Cradle has been designed to satisfy requirements for: 
¢ secure mounting for the HC 

e "hands-free" operation 

e battery recharge 

e high speed data transfer with a PC. 


The Cradle incorporates a security lock to ensure that the HC is held reliably. A trigger loaded spring 
release and hand recess guarantees easy insertion and removal. 


There is an additional i/o port, the Fast Serial port, on the right side of the machine, for data exchange 
and battery charging. It is designed to be connected directly to a Cradle. The high reliability contacts 
automatically engage when the HC is placed in the Cradle - no user-made connections are required. 


Data is exchanged via the Fast Serial port at up to 1.5Mbits/sec. 


The Cradle contains an expansion slot provided to accommodate a high-speed connection to a PC. This 
slot can be used, alternatively, for RS232, MCR, or modem modules (among others). See the chapter The 
HC in the Cradle for more details. 


HC PROGRAMMING GUIDE 


Power supply 


The HC can be powered using rechargeable nickel-cadmium batteries or an optional mains adaptor. 


The HC will not switch on if there is no power source, if the batteries are too low, or if the rear door is 
open. Power is needed to operate the HC and to maintain the data stored in internal memory. Data stored 
on SSDs, however, doesn't rely on the main power source. 


On the right side of the machine, under the rubber plug, is a socket labelled POWER. Plug the mains 
adaptor into this socket. The red power indicator light will come on. This light indicates that the HC is 
being powered by an external source, such as the mains adaptor - even if the HC itself is not switched on. 


The HC is also supplied with a small round lithium battery. This is the backup battery. It is essential 
because it keeps the internal memory secure if the main batteries are being changed. It should be fitted 
before the main batteries. However, the HC cannot be run using only the backup battery. 


To see where to fit the backup battery, remove the expansion module at the base of the HC. The positive 
side of the battery should face upwards (towards the rear of the HC). 


The backup battery should last for approximately one year, provided the HC doesn't spend long periods 
with no other power supply. It is recommended that a new backup battery is fitted yearly (if the HC is left 
powered only by the backup battery, the battery will last for approximately one month). 


The main battery cartridge is stored in the back of the HC, between the two SSD drives under the rear 
cover. It contains the rechargeable batteries. Do not attempt to disassemble the battery cartridge. 


To remove the cartridge, switch the machine off and release the back cover as for SSDs, then push and lift 
the cartridge. To fit the battery cartridge back into the HC, slide it into place and close the rear cover; the 
machine can now be switched on. 


The nickel-cadmium batteries can be recharged in several ways: 


e leave the sealed cartridge in the HC while powered from the mains - the batteries will be trickle 
charged 


¢ remove the sealed cartridge from the HC and plug a mains adaptor into it to recharge the batteries 
directly from the mains 


e trickle recharge by a standard Cradle 
e fast recharge by a Cradle supporting this facility. 


The HC can be configured so that, when either battery is low, a warning message will appear. 
Independently of this, there are a variety of software methods to monitor the voltages of the batteries. 


When the main battery is low, the HC may have enough power to display the screen and accept input from 
the keyboard, but not enough to write to Flash disk or access expansion devices. The HC 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 HC will by default switch itself off automatically, if left alone for 5 minutes. 
The "auto-switch-off" time can be changed to another value, if desired, or the HC set so that it does not 
auto-switch-off at all. 


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, if the bottom expansion port is removed, the face of the battery containing the plus 
symbol is the (partly) visible one. (This is the flatter of the two faces.) 


Lithium batteries should be replaced only with the same or equivalent type, as recommended by Psion. 
Used lithium batteries should be disposed of according to the manufacturer's instructions. 


Screen 


The normal HC screen is a retardation film LCD 160 pixels wide by 80 pixels deep. In a standard font, 
this allows for the display of 9 lines each with around 30 characters. If fewer characters are required to be 
displayed, a larger font can be used, to achieve a more striking screen image. 


Changing the font is only one example of the graphics support supplied by the resident software. 


14 


1 INTRODUCTION TO THE HC 


By default, the screen is illuminated by reflected light, using (as throughout the HC) state-of-the-art 
technology. In case additional lighting is required, a variant is available with a factory-fitted backlight. 
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). Alternatively, the HC can be 
configured to switch off the backlight automatically once a given time period has elapsed. 


Keyboard 
The keyboard features positive travel dished keys with durable legends. 


Various keyboard layouts are available, depending on how the HC is to be used. For example, 
e a full alphanumeric keyboard (53 standard-sized keys) 
¢ amore limited, number-oriented keyboard (31 larger keys) 


e the alphanumeric keyboard can be augmented with special characters used in Scandinavian 
countries - these extra characters being accessed via the PSION modifier key 


e alternatively, the alphanumeric keyboard can be augmented with special characters used in mainland 
European countries. 


The following special keys may also be present: 


ON/OFF switches the HC on and off 

BACKLIGHT switches the backlight on and off (if one is present) 

LCD controls the contrast of the LCD display 

MENU under application control 

TASK accessed via the SHIFT key: allows for switching between tasks 

INFO accessed via the SHIFT key: under application control (by default, the voltage 
levels of the main and backup batteries are displayed) 

Fl through F4 extra keys under application control 

LOCK forces the keyboard into upper case 

DEL used to edit typing 

ESC or C (CLEAR) used to clear a line of input or cancel an entry 

ENTER terminates a line of input. 

PSION an extra modifier key (analogous to ALT on a PC), recognisable by its familiar 


"cup and saucer" Psion logo. 


The basic software 


The software running on an HC 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 Shell and the Link communications 
software 


¢ application software, from an SSD or internal memory 
e library software, again from an SSD or internal memory. 


Library software is software that can be re-used by more than one application. It may be written by Psion, 
by the application writer, or by a third party. 


The effectiveness of library software and application software can be increased considerably by informed 
use of the ROM resident software - this software sets the HC apart from its competitors just as much as its 
unique hardware does. 


See the following chapter, Writing Software for the HC, for some initial guide-lines on how to write 
applications or library code for the HC. 


HC PROGRAMMING GUIDE 


Versions of the HC software 


Whilst the bulk of the material in this manual holds true for HCs with ROM version numbers less than 
1.50, parts of the manual presuppose that the ROM software running on the HC has version number at 
least 1.50. 


To see which version of ROM software is contained in any HC, type ver at the s prompt in the Command 
Shell. (Alternatively, the version number is displayed following any reset.) 


Machines with ROM version numbers less than 1.50 can easily be upgraded, using the Repro procedure 
discussed later in this chapter, in conjunction with a suitable Master SSD. 


The terms Epoc and Plib explained 


What counts as the operating system of the HC and what counts as an application depends on your point 
of view. The services in the HC ROM software that applications programmers can call upon actually 
consist of many layers - as the following few sections make clear. 


The kernel of the operating system of the HC is known as Epoc. See the Introduction chapter of the Plib 
Reference manual for a detailed list of the essential characteristics of Epoc. 


Epoc contains code to implement the Plib function library - Psion's version of the standard C 
programming library, as modified and extended for use by HC programs. 


The core ROM of the HC contains considerably more than just the Plib library: for example the Window 
Server which is responsible for the screen and the keyboard is a completely separate process the code for 
which is resident in the ROM. 


Hence in response to the ver command at the $ prompt of the Command Shell, versions numbers will be 
given for the HC ROM version number, the Epoc operating system and the Command Shell. 


Initially applications programmers will have little need to distinguish between the various components of 
the HC operating system. However distinctions do exist and it is necessary to understand them in order to 
write more advanced applications. 


Graphics window server 


The Window Server is ultimately responsible for all graphics output on the HC and is also responsible for 
channelling all keyboard input to the appropriate application(s). 


The Window Server includes support for basic text printing functions of the puts and gets variety - as 
used in the Command Shell. However, it is expected that most applications will go beyond this level and 
hence take advantage of at least some of the graphics enhancements supported by the Window Server: 


e text display in a variety of fonts and font styles (eg bold, italic), including fonts that are proportional 
as well as some that are monospaced 


e display of characters (or other small icons) in a custom-designed application-specific font 

e line, box, and poly-line drawing 

e area clearing, filling, inverting, and greying 

e flashing cursors and other animated displays, including clocks that are automatically updated 
e general bitmap and icon manipulation, eg involving maps, markers, and diagrams 

e alert dialogs, information status messages, and flashing "busy" indicators. 


It is possible to achieve screen displays which update themselves without any annoying flicker, which 
scroll smoothly, and which redraw quickly whenever required - in marked contrast to some other graphics 
systems. 


See the Window Server Reference manual for a complete description of the Window Server. 


Multi-tasking kernel 


From the beginning Epoc was designed as a pre-emptive multi-tasking operating system. It is multi- 
tasking in that multiple processes can run concurrently and exchange data dynamically. It is pre-emptive 
in that a lower priority process is always interrupted when a higher priority process is ready to run. 
Routine processing can always be sent into background if the user has something more urgent to attend to. 


1-6 


1 INTRODUCTION TO THE HC 


Often an application is best written as two or more components each of which implements part of the 
applications overall functionality. Under Epoc these processes can run concurrently and exchange data as 
and when required. While one process is sitting idle waiting for an event another process is being run. 
When the first process receives the event it too starts running immediately with no idle waiting for the 
second process to complete. 


Often the user will require two or more applications to be running at the same time. Under Epoc the user 
can ask one application to print a large text file and then use another application for editing a second text 
file. The only restriction is that no more than one application may access a given hardware device at a 
given time. In the example the first application is accessing the serial (or parallel) port. The second is 
accessing the screen and the keyboard. Thus there is no conflict. 


To switch between applications provided with a user interface the user can press the TASK key. This 
simply brings the application into the foreground. Applications software may provide additional 
mechanisms for bringing applications into the foreground. 


Writing various programs separately and then giving the user the opportunity to combine them as required 
- depending on circumstance - naturally adds to the attractiveness of a suite of software. For example the 
shell component of the operating system - the Command Shell which is supplied with the HC - can easily 
be replaced with a third party shell as long as it is given the appropriate name (sys$shil.img) and fulfils a 
few basic functions. The Window Server may also be replaced although this would be a very complex task 
and is thus not recommended. Less radically the applications programmer should consider supplying 
processes that run alongside the in-built ones and which add to the overall functionality of the HC. 


Support for asynchronous i/o 


A central concept that underlies user friendly interfaces is the idea that the computer should not be held 
up indefinitely, waiting for an event to complete. For example, the user should always be able to cancel an 
aberrant data transfer, or a mistaken print request, without having to resort to resetting the computer. 


Part of the support Epoc provides for this is its multi-tasking capabilities (see above). Another part is its 
large range of asynchronous i/o services. Rather than just having a request, for example, to print a line 
(and to wait until the line has indeed been printed), there is a request to print a line and to notify the 
program when the line has been printed leaving the program free to process other data input in the 
meanwhile. 


Another reason why asynchronous services are of fundamental importance is that programs often cannot 
tell which of two events will be the next one to occur - where the events include not just input from the 
user, but also a variety of communications data and other peripheral input. Again, a subprocess may 
report that it has finished some lengthy activity, such as scanning a large database; a supervising program 
would have to be ready to respond to this notification, as well as being ready for any other kind of data 
input. Programs ought to be structured to cope with any of these events being the next one to occur. 


Traditionally, function libraries offer poor support for asynchronous services. Not so the Plib function 
library that is built into the HC ROM. 


Database support functions 


The Plib file i/o functions can be used for any variety of data formats on file, and HC programmers can 
choose whatever they feel most comfortable with. 


However, much can be said in favour of the Dbf file format: 
e ROM-resident code provides a rich set of services to simplify access to files of this format. 


e it is designed with Flash-friendliness as a high priority, with incremental file modification as 
individual records are updated. 


e services such as random and sequential access are both highly optimised. 
e other services such as merging and compressing databases are easy to use. 


For larger or more complicated databases, programmers may consider using the JSAM (Indexed 
Sequential Access Method) library that is separately available to support program development. The 
ISAM routines mesh closely with the Dbf services in Plib. See the JSAM Reference manual for more 
details. 


HC PROGRAMMING GUIDE 


Support for remote file access 


In contrast to just supporting remote file transfer - a notion familiar to most users of computers - the HC 
operating system supports the more radical and far-reaching notion of remote file access. In many 
situations, remote file access is altogether the more convenient way for software on one computer to 
interact with some data stored on another computer. 


To clarify the distinction between remote file transfer and remote file access, consider some software on 
an HC, that from time to time accesses a database stored on a central PC. One method to achieve this 
would involve the following steps: 


e transfer a copy of the database from the PC to the HC 

e have the HC software operate on the local copy of the database 

e finally transfer the copy of the database back from the HC to the PC. 
Two separate pieces of software are involved in this: 

e the database application running on the HC 

¢ some communications software, implementing the file transfer. 


However, with remote file access, the database software on the HC directly accesses the database file on 
the remote computer. There is no need for some independent software to copy the whole database from PC 
to HC and then, later, back again. Instead, the operating system of the HC automatically transfers only 
that small part of the data in the database that the software on the HC needs to access. 


At one level, the way this works is by an extension of the concept of a filename. Traditionally, the full 
specification of the location of a file on a computer would have been something like 


a:\project\library\backup.c 


However, in the view of the HC operating system, this name is actually incomplete (though it suffices for 
many purposes); strictly, speaking, the full specification of the location of a file on an HC would be 
something like 


loc::a:\project\library\backup.c 


with the leading Joc:: indicating that the file is on the Jocal computer. To gain direct access over a file on 
a remote PC, a filename such as 


rem::c:\hc\backup.c 


should be specified - with the leading rem-:: indicating that the file is on the remote computer. Given that 
the computers are connected appropriately, observing the correct naming conventions is all that an 
application needs to do to gain direct access to files on the remote computer. 


In some ways, the remote file access facility of the HC operating system can be compared to the way that 
networking software provides additional drives on desk top computers. Thus a PC which ordinarily has 
drives A: and C: may gain drives N: and U: when connected to a network - these additional drives 
allowing access to files stored on the network server or on other computers linked together by the network. 


But in another way, the remote file access in Plib is considerably more general; this is why the additional 
drives appear as another filing system. The point is that access is permitted not only to a PC connected to 
the HC, but also to one of many other types of computers, such as Apple Macs. 


For example, to specify a file on an Apple Mac connected to an HC, the following filename might be 
given: 


rem: :hd40:mike's folder:november:results 


where it should be noted that the form of the filename is quite different from that allowed by MS-DOS (eg 
containing spaces and having more than eight letters in a directory name). 


For more details, see the section below on Connecting to other computers. 


1-8 


1 INTRODUCTION TO THE HC 


Other ROM-based library services 


In order to fully appreciate the Plib library it is necessary to read the documentation in the Plib Reference 
manual. 


Features worth noting include: 
e a full range of mathematical and scientific functions. 
e file management and filename manipulation functions. 
e support for reading and writing environment variables. 


e support for dynamic memory allocation inside and outside the native data segment of an 
application. 


¢ support for absolute and relative timers. An application could for example switch on an HC and 
perform a preassigned task at a preset time. 


¢ control over the HC system set-up. Thus an application could for example set the auto-switch-off 
time, change the language used, and adjust the LCD contrast and backlight setting. 


e sophisticated support for error handling. 
e special support for advanced object oriented programming methods. 


Other ROM components 
Additional files in the ROM include 


custom$.dat a specially customisable file that can be written to once and once only 
sys$shll.img the Command Shell, as described in detail in a separate chapter 
sys$ntfy.img the basic Notifier process, used by default to report error conditions (such as 


missing SSDs) 


sys$ctry.cfo the location of all the language-dependent text strings used by the operating 
system, as well as keyboard layout information 


opl.dyl allows programs written in Opl to be run (see the Op! Development Kit for 
more information) 


olib.dyl provides additional services that object oriented programmers can access (see 
the Olib Reference manual) 


batchk.img displays information about battery voltage levels 


pprint.img prints a specified file via a nominated peripheral (likely to be omitted from 
future versions of the ROM) 


ttest.img tests the status of the serial port (likely to be omitted from future versions of the 
ROM). 


Additionally, the ROM contains a variety of programs and device drivers to facilitate communication with 
other computers - be they PCs, Macs, computers in the SIBO range, or whatever. Chief amongst these is 
the Link program, described in more detail later in this chapter. 


Finally, the ROM also contains a number of built-in fonts (*,fon files). 


Footnote: to obtain a listing of all the files in the ROM, type dir /p rom:: at the s prompt of the 
Command Shell. Note 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::. 


HC PROGRAMMING GUIDE 


Customising an HC 


This section describes some of the many ways an HC can be customised, to make it ideally suited to some 
particular set of needs. 


Hardware customisation 


The HC can be customised to suit customer requirements. 


Simple examples of hardware customisation include changing the labels and branding, changing the 
colour scheme and replacing the keyboard legends. 


More complex examples of hardware customisation include changes in the keyboard layout, changes in 
the size of the LCD, and changes in the assembly of the LCD allowing operation in more extreme ranges 
of temperature (the cold of the arctic for example). 


Further details of hardware customisation are beyond the scope of this manual, which focuses mainly on 
software customisation. 


Replacing the built-in Shell 


The Window Server will when the HC is first switched on (or following a reset) search for the shell 
program stored in the file sys$shil.img. The search is carried out as follows: 


e first in the root of a: 
e then in the root of b: 
e then in the root of m: 
e finally in the ROM. 
On finding the shell program the Window Server will start it running. 


Unless specially customised to the contrary, the Window Server also looks for a program of this name, 
along the same path, whenever the shell terminates (either normally or abnormally) - so as never to leave 
the HC without a shell running on it. 


The importance of this is that the shell program in the ROM can be over-ridden by one on an SSD. HCs in 
the field will typically be running a shell from an SSD, rather than that from the ROM. 


The ROM shell is more suited to 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 HCs running application 
software. 


By and large, applications writers will most of the time use an alternative shell, switching back to the 
built-in Command Shell only when the need arises during program development. 


Switching from the Command Shell to a custom shell on an SSD involves 
¢ inserting the SSD containing the custom shell 
e tasking to the Command Shell 
e typing term sys$shli (termis short for terminate). 
Switching back to the Command Shell from a custom shell involves 
¢ removing the SSD on which the custom shell resides 
¢ terminating the shell, either by a command supported by the custom shell, or by resetting the HC 


e the Window Server, in restarting the shell, will no longer find the custom shell, and hence will 
start the Command Shell from the ROM instead. 


One reason why, even during development work, the Command Shell may not be required, is that most of 
the basic functionality the Command Shell provides can be duplicated by commands transmitted down a 
serial connection from the PC to the HC. These commands can be invoked either using the SIBO 
Debugger, or using MCLink. 


1-10 


1 INTRODUCTION TO THE HC 


A program developed as an alternative shell would typically have another name during development, such 
as hcshell.img. It would be renamed to sys$shll.img only at the last minute. Otherwise, other SIBO 
programs, such as the SIBO Debugger, might fail to work, on account of finding this alternative shell and 
attempting to run it instead of the appropriate shell that is built into their own ROM. 


Resetting the HC 


It should rarely be necessary to reset the HC. Even if, during development, an application contains some 
dreadful bug, this is most unlikely to cause the entire HC system to hang. 


For example, any illegal attempt by an application to write to data outside its own data segment will lead 
to the operating system terminating the application forthwith, in a so-called panic. Likewise should an 
application leave interrupts disabled for too long. 


However, the worst may come to the worst and a reset may prove necessary. Alternatively, it may be 
required to reset the HC, just in order to terminate one shell process and to cause a new one (say that in 
the ROM) to be started instead. 


Before resetting, it is wise to first terminate all applications and save any important data to an SSD or 
a PC. 


To carry out a soft reset of an HC, insert the end of an opened paper-clip into the reset hole (located just to 
the right of the microphone). This will re-boot the HC forcing the abandonment of all programs running 
at the time and the consequent loss of the associated data. The files in the internal memory (m-) will not 
be lost. 


To carry out a hard reset hold the ON/OFF key down while pressing the paper clip into the reset hole. This 
will erase all internal memory including environment variables. 


Reproing the HC 


For some applications, an alternative mix of files on the ROM may be required for special customisation 
purposes: 


¢ programs run out of ROM have less of a RAM overhead than those run from an SSD. 


¢ 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 is described in the chapter Customising the HC 
Rom, later in this manual. 


The process of transferring a .mas file into the ROM of an HC is called reprogramming, or reproing for 
short. Reproing can be used, not only to produce a specially customised version of the ROM software, but 
also to upgrade an earlier ROM to a more recent one (say to ROM version 1.50). 


Reproing requires a master SSD, which contains both the .mas file and the repro software itself. Note that, 
counter-intuitively, reproing will not work if the master SSD is write-protected. 


During reproing, the HC should be powered from the mains. As a precaution, it is wise also to have a 
charged battery in the HC: if the power fails during reprogramming, the HC will need to be sent back to 
Psion before it works again. 


The master SSD should be placed in either of the SSD drives and the rear cover of the HC closed. Type 
repro followed by ENTER at the $ prompt of the Command Shell. Once the HC has displayed the new 
master details, press ENTER again to confirm reprogramming. 


On HCs with the 31 key numeric keyboard, it is impossible to type repro, so type the following instead: 
YES 0 NO 0 ENTER 


The message yono will appear on the screen, and then repro will run as normal. 


HC PROGRAMMING GUIDE 


During reproing, the HC displays large characters on the top line of the screen, starting with aooo. In all, 
four rows of figures will eventually be displayed. On completion, the HC will emit beeps, and an 
automatic reset should occur. Occasionally, the automatic reset may fail to occur, in which case a hard 
reset should be executed (as described above). 


As usual following a reset, the automatic search that takes place in these circumstances for a file 
autoexec.btf can be circumvented by pressing PSION+ESC (or, on keyboards with no ESC key, SHIFT+C). 


Once reprogramming has completed, the new ROM version number can be determined using the 
command ver in the Command Shell. 


Note that (in contrast with the case of reproing the laptop MC computers) no additional hardware repro 
enabler is required in order to repro an HC. 


Master SSDs and masicpy 


The master SSDs used during reprogramming cannot be duplicated using ordinary software (such as the 
copy command in the Command Shell). More precisely, only part of the contents of a master SSD can be 
copied in this way. 


However, a special tool is available, called mast cpy, which can make a copy of a master SSD. 
The mastcpy program runs on a PC with an external SSD drive. 


Once-off ROM customisation using Romwrite 


As an alternative to reproing an HC with a specially customised ROM, it is possible to customise it by 
overwriting, in a special way, the contents of the file custom$.dat that is in the ROM. Typical uses of this 
mechanism include 


e adding special information such as serial numbers or details of the owner. 


e loading an alternative set of language text, containing versions of such operating system 
messages as "Low main battery" and "No system memory" in a foreign language. 


In order to write to this file, the special tool romwrite.img (available as part of the SDK) has to be used. 


Note that romwrite can only be used with HC ROMs with version number 1.50 and above. Mains must be 
present for romwrite to operate. 


Romwrite copies the contents of a file supplied by the user, with the name custom$.ref, into the ROM file 
custom$.dat. The file custom$.def must be placed in the same directory as romwrite.img. A maximum size 
of 4608 bytes is allowed for custom$. ref. If this file is larger than 4608 bytes, only the first 4608 bytes will 
be copied into ROM, and no error will be reported. 


Romwrite appends two further bytes to the end of the copied information. These are required checksum 
information. 


To invoke romwrite: 
© copy romwrite.img and a suitable file custom$.ref to an SSD. 
e place the SSD in the HC. 
¢ connect a mains adaptor to the HC. 
¢ type romwrite at the $ prompt of the Command Shell. 


An error message will be given if the file custom$.dat in the ROM has already been written to, or if there 
were any problems in writing to the internal ROM. 


Warning: if a write error occurs during romwrite, the HC must be reproed from a master SSD before 
being used any further. Do not reset the HC. 


Once the contents of custom$.dat have been overwritten using romwrite, they cannot be overwritten again 
until the ROM has been reproed. 


Reproing entirely loses the contents of this customised file. However, the contents are unaffected by any 
reset, even a hard reset. 


1 INTRODUCTION TO THE HC 


Customisation for copy-protection 


One additional use of the file custom$.dat would be to frustrate illicit copying of software (see also the 
chapter Copy-Protecting Software in the General Programming Manual for discussion of alternative 
methods with the same end). 


Briefly, when an application is started, it could read the contents of custom$.dat, looking for a pre-defined 
byte-stream signature. If this signature is not present, the application would refuse to run. 


The signature would have to be written beforehand, into custom$.dat, by means of a special installation 
program. Possibly, the software company producing the application would make a special charge to 
administer the installation program (whose details would need to be kept secret). 


Connecting to other computers 


Connections between an HC and another computer, such as a PC or Mac, can be divided into two sorts: 


e high speed connections, which require the HC to be located in a Cradle and which generally also 
require the PC to be fitted with an ASIC-2 expansion card 


¢ = standard connections, which simply require a standard serial cable between the HC and the other 
computer (no expansion card is required in this case). 


High speed connections are discussed more fully in the chapter The HC in the Cradle. The remainder of 
this section focuses primarily on standard connections. See also the chapter Mclink, Mcprint, and Slink in 
the Additional System Information manual. 


Basics of serial connections to an HC 
Any connection between two computers involves a hardware connection and a software connection. 


When an HC is connected to another computer, the software connection will generally be via Epoc Link 
software. A version of this software has to be running on each of the two computers. 


The Link software can be started on the HC simply by typing 1ink into the Command Shell. One way to 
start it on a PC is to invoke the executable mclink.exe (similar programs also exist for other types of 
computer, such as Apple Macs). 


The hardware connection between a PC and an HC, when Link software is running, can involve either a 
custom RS232 cable plugged into the PC at one end and the HC at the other, or a High Speed Serial 
connection via an HC Cradle. 


RS232 connections 


Modern PCs have 9-pin sockets on serial ports; older ones have 25-pin sockets. If you only have one serial 
port on your PC, it is called COM1, although it is common for PCs to have a second serial port called 
COM2 (COM3 and even COM4 are also possible, but the Link software does not support these). 


Connect the appropriate socket at the PC end of your cable to COM1 if is available - otherwise, use 
COM2. Link software on the PC sees COM] as Try:a and COM2 as try:B. Alternatively, these can also 
be referenced simply as "pl" and "p2" (for ports 1 and 2). 


To specify that MCLink uses port 1, type 
mclink -pl 
at the MS-DOS command line. Likewise type mclink -p2 to specify port 2. 
The socket at the HC end of the cable plugs straight into the serial port in expansion modules of the HC. 


Summary of straightforward usage of Link on the HC 
The Link software on the HC can be started by typing simply 1ink at the Command Shell $ prompt. 


To terminate the Link software at some later date, type term link. 


To discover whether or not Link software is running, type lproc link. 


HC PROGRAMMING GUIDE 


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. 


Link allows a HC to open or save files on a remote computer in the same way as it opens and saves files 
on its internal memory and SSDs. Conversely MCLink allows a remote computer to open and save files on 
an HC in the same manner. Note that al/ HC applications automatically possess the ability to access 
remote files in this way - no special "comms software" has to be added into the applications. All that is 
required is a degree of agnosticism regarding the structure of filenames: eg it must not be assumed that 
directory names end in 'V characters, nor that the core parts of filenames are restricted to eight letters in 
length. Provided appropriate Plib library routines are used to manipulate ("parse") filenames, remote file 
access comes free. 


The user should note that the Link software must be left running all the time that files on the other 
computer are being accessed. 


Why not MS-DOS? 


Some would-be HC applications developers may be put off by the fact that the operating system of the 
HC is not MS-DOS but Epoc. On the face of things, this poses two problems: 


¢ applications written presupposing MS-DOS have to be rewritten before working on the HC 


e there is a learning curve that has to be negotiated, in coming to terms with the differences 
between Epoc and MS-DOS. 


With regard to the first point, there is, frankly, no way standard MS-DOS applications can transfer over to 
the smaller screen of a handheld computer without some amount of re-writing. The reduced screen size of 
hand held computers actually means more than just "compressing" the screen display from say 80 
columns to around 30; it means having to rethink some of the user interface completely (as many displays 
simply won't work in their original form, if they are compressed by such factors); the quantitative change 
in screen size is such that it in turns leads to a qualitative change in the user interface supported. 


However, this consideration is incidental to the main point, which is that Epoc is simply an operating 
system far better suited to the particular needs of computers such as the HC. 


Some of the special advantages of Epoc over any version of MS-DOS are: 


e amuch more sophisticated power distribution system can be managed, resulting in significantly 
longer battery lifes than could ever be achieved under MS-DOS 


¢ pre-emptive multi-tasking is natural to Epoc, but is artificial (and hence expensive) to MS-DOS 
e¢ Epoc supports remote file access in a way that, again, is expensive to emulate in MS-DOS 


e Epoc implements address trapping (on an 8086 chip!), amongst other measures, to prevent 
aberrant processes from causing a system crash: just consider how many times PC developers 
have to recourse to the "big red switch" when an aberrant MS-DOS application results in fatal 
damage to PC RAM contents, and compare this with how few times a corresponding measure is 
required during HC development 


e Epoc allows a change in which device drivers are loaded, without the computer having to be 
reset. 


Briefly, Epoc results in smaller programs which execute more efficiently and in a manner more in line 
with the intuitive expectations of end users. 


This applies for the programs built into the ROM as well as those developers might write. As a result (and 
this may well be the bottom line), HCs end up considerably cheaper than any corresponding MS-DOS 
computer. 


What actually lies behind the initial hesitation of many would-be HC developers is concern over the extent 
to which files written by MS-DOS programs on PCs can be read and updated by Epoc programs on an HC. 
Understandably developers are unwilling to upset an existing successful PC setup, even if they are 
prepared to learn a new programming system for the HC parts of the overall computer system. 


1 INTRODUCTION TO THE HC 


However, developers can rest assured that there is no inherent difference in file structure between 
MS-DOS programs and Epoc programs. Epoc is fully file-compatible with MS-DOS. 


Furthermore, it should be re-emphasised that many existing programs will transfer fairly smoothly from 
an MS-DOS environment to an Epoc environment. This is the role of the Clib library, discussed in more 
detail in the General Programming Manual. 


Finally, bear in mind what some experienced HC developers have said: that it is actually quicker to 
develop programs for the HC than it is for the PC. In part, this is due to the rich Software Development 
Kit (with high-powered libraries) available for the HC. But it is also in part due to the fact that Epoc is for 
many purposes a superior operating system. Accordingly, the Epoc learning curve is one that is well worth 
climbing! 


CHAPTER 2 


WRITING SOFTWARE FOR THE HC 


Basic programming choices 


Choice of programming language 
The two main high-level programming languages for the HC are Opl and C. 


Whilst Opl has many points in its own favour for smaller projects (discussed in the Op! Development Kit), 
the following points are likely to sway any competent programmer to use C for any more substantial 
application on the HC: 


e Ccode executes more swiftly. 

e Cisaricher programming environment, with abstract data structures, pointers, and typedefs. 
e It is generally much simpler to call routines in the OS from C than from Opl. 

e Programmers with experience of C have no need to learn Opl. 


e¢ Code written in C for other products on other hardware can obviously be converted more quickly 
into C for the HC than into Opl for the HC. 


e Conversely, code written in C for the HC is more likely than Opl code to have parts that are 
portable to other projects; in this sense, programming in C is a better long-term investment. 


Occasionally, some code may have to be written in assembly language (for example, when writing a 
device driver). 


Standard C (Clib) or Psion C (Plib) 


A significant proportion of C code that companies have already written for other target computers can be 
transferred almost straightaway to run on an HC. All that is necessary to do is to recompile and re-link the 
code. 


To take a very simple example, the program simple.c 


#include <stdio.h> 


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 <p_std.h> 
#include <p_sys.h> 


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 <p_std.h> 
#include <wlib.h> 


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 
| <text> 
at the MCLink command line is shorthand for typing 
run sys$shll <text> 
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) <o4> or <o1>. 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<baud>] [-p<port>] [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: 


<launch program asynchronously> 
<some processing> 


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 <p_std.h> 
#include <p_file.h> 
#include <p_sys.h> 


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 <p_std.h> 
include <p_file.h> 
include <p_sys.h> 


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: 


<full path of the original name>[,<name by which the file should be called inside the 
rom> ] 


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: 


[<byte count><name><byte count><value>] 


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 


