sibo-playground/docs/1-05 EPOC OS System Services 2.30_djvu.txt

SIBO 'C' Software Development Kit 


EPOC O/S SYSTEM SERVICES 


Version 2.30 


March 1, 1999 


(C) Copyright Psion PLC 1990-98 

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

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

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

Intel 8086 and 80286 are registered trademarks of Intel Corporation. IBM, IBM XT and IBM AT are 
registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered 
trademarks of Microsoft Corporation. Psion PLC acknowledges that some other names referred to are 
registered trademarks. 


CONTENTS 


DTG OGuiC ts, isi eccci ss ce casisccctesecedeccsnccsstcsscodeccseecedesdecsdeccdececesssscedsccsnecstecdscedeccsssececedecedecessecestes Ld 


SYSCEMM SEL VICES oi heh: suk veloeehs gcbedua vudewes saebeduh ods conte cebede pub coves cousvah edtbewstocebebenedtigweseeuhienonst 
Single service:interrupts ::.43:8Ascniiao sss ob de adehl Adenine s Ag 
Multi Service titerrupts's.esic.s3isstecstuts Seeeduveteossets Seeded sduvsesbaduesduysdeusteda dice dubsduectedsdyvadevednes dS 
Gallin S COMVENHONS .i5.45iudssvcsasaciasetaaseeest dash svandasatea io cananthzestaasapeanaoasgestessanessaashosetaswetess 
Documentation conventions 
Include file epocdefs.inc 


2 Segmented Memory Management ...............ccsscccsssssscsscsscssscsecssccsesssscscesssscssesssccscsssssssesssscssees DOL 


Memory Segment naimes::i.ci:4cc.tistscssdaicesnigthosndshecetintiosnads ht eetdathesnnda beeetgatbosadaitiestdabas 
Paras raps ns. cic; sh. chchcs cobs seeks dokcces Sees gua hacetcaes cous euch sdeewes cqunguske ocd ede Suvsgunbeces eoes Syuagunnecedetes boue 
Permanent se@iments so: i.c508 Viste hab aihisien es Asians Aaehilen Sai ache 
Directlyaccessin g: S6SiMeNts sai. et sakess aaches cessdieseeva deesecssduessscadeesecbideostetaceeedusadevssdyvedetaluneds 
Size of available segmented MEMOTY ...........c ce eeseeeeseeesseecsseecesseeesseecsaeecscesseecesaeeesaeeesaeers 
Creating a memory segment 
Deleting a memory segment 
Opening a memory segment % 
ClosinS:a;memory Seement 5: .12:.3:5:45..1daisoeesacsvodendaiscsssactasseadaustestaacassendateaetaatassndaseasseaiay 
Closing a locked or device SCQMENE........ eee eeseeeeseeeesneeesneecseecsseecesaeecsaeersaeeseneeeesaeeesaeers 
Locking a MeMOFy SCYMENL........ eee eeeececeeseeceeeeseeececeeeeeeeseaeeecsesneeeceeeeeesseaeeeeeeseeeeeeaees 
Unlocking a MeMOTY SCYMENL «ue eee eeeeceseeeeseeeseecseecseeceseecesaeecseaeessneeeetaeeeseeesaeers 
Size‘of A MeEMOory SESMENE: s355:cisscsiszcssdalssesteseapesidsnscestegnapeahastsrestadsapeandgasoeedeass deusacenouetadase 
Adjusting the size of a memory segment 
Finding all s@ornents o.xisc3 4. oscek desedass doavices covudanscesvideatsazssveedata ds sadunacvas seach stbaaarete sade aobeaares 
Copying to a MEMOTY SCYMENE ........ ee eeeeeeeeeceseeeeseeesseecseecscecsseecesaeessaeecseessseaeeesseeesaeers 
Copying from a MEMOTY SEZMEN....... eee eeeeeseeesseeeeseeeceeecseeceseeeesaeecsaeessaeeseseeeesaeessaeers 
Size OP RAM disk s:. cu ssisea shi neler ed adiaoki ded casi ne ole ciel 


3 Heap Memory Management ...............ccccscccsscssscssscssecssscscecsscsscsssscssccssccsesssscssscsssscssessssssessssees OU 


Dynamics:Of hedp mem Ory: i.5 ess.2¢ssco0s hes feist ss cog danheeevdsbestieatas, Hee easebalin fos chesdeystheed 3-1 
Allocating heap MEMOrys: .sc..iisBesstsaticestiahassitascessataocsidaatgesbeedateuensealeatieostosungeaseatheestans 3-1 
Re-allocating heap MeCMOTY.............seccesssecsssceesseeceseeeesseecsaeecseecsseesesseeesaeesseeseneeeeseeeenaes 3-2 
Adjusting the size of heap MeEMOTY................secesecceseceeseeeesscecesceceseeceseeeesacecssnecsseeseseeeeners 3-2 
Freeéms heap Memory x .2. 5:0. eck. codsdavssta davis coisteszdes Sbvke eedazeosdeu ubke fubadevsdon Stbbe peaduuaion aheaelo2es 3-3 
Size’of a:heap, cells: scssstsiavicisseslascsadaseassea lace aadacieastesiaocandacdeasteaaoeaniaisoasteaiaoeasacboesteayse 3-3 
Setting the heap: sranularity «nsec scadneciodtas ou nelendidshasio ied ost glibelsieveess 3-3 
Size.of available heap Memory 25:52:35.5 fos: ase sbereedash aaedesdeaediesnd assdiadeendasiansyiaonseeths 3-3 


4 Semaphore Management ..............cccssssccsscssscssccsecssccssscscesssscsessssccsccscscsssscsesssscsseessscssssscessess Ged 


Creating a semaphores. :ci2issccanschasiehis itt eedatiosatdadcsaacstaneaneatieassboeadiodgdelesteoeaiguavenetas tees 4-1 
Deleting a semaphore.............cecccceeesscceessnceeceeeneeecesceeceeeneeeceseeeceseeeeeeseaeeeeeseeeseneaeeeseeanees 4-1 
Waiting on a Semaphore..........e.ccceseecccesssceeceeesseeeceeneeeeceeaeeeeseeeeecesnneeesseaeeeeeseaeeeeeenneeeeeeee 4-1 
Sie tall SON Ce ees’ ivis 505 seh eek Sees ects aes ted saves eed deve ee does eat Fee teasoeks dubs Sealed te Geese thy 4-2 
Signalling More than Once s....::ssctedsiesteaiateatlaeetesiscsatledsetensteetlidostasecentlaoeteaeiens 4-2 
Signalling once without re-schedule......... eee eeseesscecsseecsseecesseessaeecsaeecseecsseecesaeeesaeeesaeers 4-2 


March 1, 1999 


EPOC O/S SYSTEM SERVICES 


5 Message Management ...............ccccccsssssssccsssccccsscceeccssssscsssceseccssscscecsseesccsssccsssessssssssscsssseeesssssees 5-1 
Inter process COMMUNICATION ............:ceeeeeeeceeeeneeeeeeeeceeeeeeeeeeeeneececeeenaeeeseeeeeeeseaeeeseenneeeeeeas 5-1 
Order of Message TECEPLION ice ciccciseeicveisetdccoigerdceeseenccevsdandeevedeaseesddaalesuedebdesuddesdeeidenisanecs 5-1 
The message system and the I/O system .............cessccceeeessceceesceeeeeeeeecesseeeeessneeceseaeeeeseaees 5-2 
Initializing the message SYSteM ............:cceeecseeessseceeeeeeeeeeeeeeeeeeeaeeeeeseaeeeeeenaeeeeseneeeeentaeeeees 5-2 
Asynchronous message reception ...........::ccceeecceeesseceeeeeeeeceseeeecensaeeeceseaeeeeeeaeeeeensaeeeeseanees 5-2 
Synchronous message reCeptiOn............csccceeeescccessseceeeeenceeeeeeeeeceenaeeecsseeeeeseeeecesteeeeeenees 5-3 
Cancelling queued message reCeive ...........cceeccceeeesceceeenececeeeneeeeseaeeeeeseaeeecseeeeesesaeeeeeenees 5-3 
Senin S MESSAGES... usdescesesesvetacsceuevas deveiuade ces scan cose dcanccvu cena dev deaacenvedaa Ooaucedascuccnaevandeneevandes 5-3 
Sending and getting a reply asynchromouslLy ..............:::cccesecceeeeesceeeeeeneeeceeeneeeessnneeeeeeeeeess 5-4 
Sending and waiting for a reply..........ececccceessccceceeeeeceeceenceceeseneeecesnneeecseeeeeeenaeeeeseneeeeeeeee 5-4 
FTGCii SA MeSSAGe aia ass ree aeons eeags Saves See Uelet ash Sail eae asOutess caved exe sbuutads Cousleseedlabeds cust eesescteseuals 5-4 
Requesting a signal from the SUpervisOL............:c::cccessseceeesenceeeeeeneeeeeeneeceeeeeeeeeseaeeeeeenees 5-5 
Cancelling requested signal from the Supervisor .............cccesecceeesenceeeeeseeeeeeeneeeeeenneeeeeeaeees 5-5 
Cancelling requested signal from the Supervisor by type ...........::::cceseesseceeeseeeeeeeteeeeeenees 5-6 

6 Dynamic Library, Category and Object Management...............ccccsssccssssssccsscsecsssseessssceeeeees 6-1 
Pabrary Names 5 iss scaisesescatsseusta heels tas itatienatlalieentaaectlaieenitataelbatiec ts tecatis teats tates 6-1 
Loading a dymamic library............cecesccecessccceeesneeeeeseeeeecsenneeeeeeaeeeceenneeesesaeeeeeseneeeseenneeeeneas 6-1 
Unloading a dynamic library ...........ccccccceeeeccceessncceeeesaeeeeeseneeeceeeeeceseaeeeeessneeeessneeeeeeneeeess 6-2 
Banikanig 4 dyinarnie MaDrary cues sic: ese we cevs iuadevs ca vaces dana devs cana covtaiia tuvtalvecavhdin ofutteaeveest da ceaase 6-2 
Getting a dynamic library handle ............eeeccceceeecceeeeneceeesneeeeeeseeeeeeeneeeeeenneecessneeeeeneeeeess 6-2 
Getting a DYL handle by numbe’............... ce eeecccceseccceeeeneeeeeeeneeceeeneeeeeseaeeeeeseaeeessenneeeseees 6-3 
Creating an object by mUMber ............ceecccceeesccecesneeeceseneeeceeeeeecessaeeeeesnaeeeeeseeeeeneaeeeeeenees 6-3 
Creating an object by handle .0..........eeeecccceescccecssnececeesneeecesneecessaeeecessaeeecseneeeseseeeesenees 6-3 
Destroyii ean, ObjECte: iceitazssssusdasesstislacoutaadosetes aosendarsncatealaasntaaoesigasaeundasoeateniagcandateee? 6-4 
SemMGIMS a MESSAGE a5 5 coca se voctek Sesedes Sewsatehs gveanen cqusatetegenetancnonetenaunenen oeveemens dubecen puvedeensintett 6-4 
Sending a superclass MeSSAage...........ccseccccesseceeessnececeeeeeeceeneececseeeeeeseaeeeeesneeeceeseeaeeeeseanees 6-4 
Sending a direct MesSAGe ies vss ks se. seekeseese Na syen cubase ese based cuvtoyeceavasyun cova dyede cds Fyekdeveaneeces ieee 6-5 
EMiter: a; SNE MESSAGE ssicccsssvasevuecasceekegesdaanecaacousad sag ootadaadecassuagennaaesdenssdvapeatesuaGayssaueseaseecatads 6-5 
Open a multi library file... eee eeeeccceessceeceeneeeeeeeneeeceeneeeeesneeesseaeeeceeeaeeeensneeeeeneaeeeess 6-5 
Loading a multiple dynamic library..............ccceeecscceeescceeeeeneceeeceseneeeeeseeeeeseaeeecesnnseeeseanees 6-6 
Reclass an object by NUMDED ...............ceeeccceeesnceeeesneeeceeeneeecesneeeensaeeeessnaeeeesseeeeeneaeeeeneaaees 6-6 
Reéclass‘anobject by Wandle v2.3: vssscsiassudetowsteslassentavsneataaiarcutasaverigsincecandanseearagiateardarsee cd 6-7 
Copying data from a Cate QOry........escccceessccceeesnsceceeeeeeeeeseeeeeeeaeeeceseeeeeeeaeeeeseeaaaeeeseenneeeeeees 6-7 
Enter a:control Tést0ns, toes. dete hathiacdets a Bdeoiatdenaci edo deed titi lt 6-7 
Lea vitte a 'COntrol’ Te G1 OM )c225 esi ces Fees Beiet wes 08 hea 00aGa wes Syus Daete sec S aah ue (Seta eee 0a yen SeeS Ryka Ts danse 6-7 
Returning from a method. ...........ccccceeesscceeeseeeeeencecceeeaeeeceseceecesseeecsenaeeeessneeeeesseeeesenees 6-8 

7 Device Managemen ............ccsscscccsscsssccsscssccssscscesssccscessscscesssscscssssssessssscsesssscssesssssesssssesesessees 7-1 
TIEVICETIAIMES 602. Aosed sets out te ooes oats arcutieds oobertiAdenetedeticne dea sciotedoteboveck eonttedecuavedscctetedomdssecoee 7-1 
TJOVICE=ATI VETS o35 osteo ebes eee ce eae ea oe aio ok oe An oo Sls ON ot ies 7-1 
Opening a physical device Ariver......... eee seesecceseecesceeseecseecseecsseesesaeeesaeessaeesseeesseeeesaes 7-1 
Getting the PDD entry point... ee eeeeeesecsseeeeseeeesseecsaeecsscecseecesaeeesaeecsaeecseeseseeeesaes 7-2 
Installing a device Ariver ...........ccceeceescceceesecceeesneeeceesneeeceeeeeceseaeeeeseeeeeeeeaeeeesseneeeesenneeeeeees 7-2 
Holding all device Arivers............ccceesscccceescceeeencecceeseeeecseeeceeseaeeecesneeeeeseeeeeeenneeeseenneeeeeeae 7-2 
Resuming all device Arivers.........e ee eeseesseecssceesseeceseeeesseecsseecscecsseecesseeesaeecsaeesseeseseeeenaes 7-3 
Loading a logical device Criver wi... eee ceeeeeesseeesneecssceceseecesaeecsaeecsacecseecsseeeesaeessaeessneeeeee 7-3 
Loading a physical device river .........e sc eeeceeeseeesneeceseecsseecesaeecsaeecsacecseecseeeeesaeessaeesseeeees 7-3 
Deleting: a device driver. c.csss. coseeigeiydik ogcestegisdesh be pheek eenadi gies Hesaylesbedenaghdesupbeseeeyeeideges 7-3 
Removing a device Ariver ............ccsscccceessceceeseceecesncecessaececessneecessaneeceseasesesuneesessaseeeseanees 7-4 
Querying the number Of Units ..0........ ce eeecccceeecccecesnececessneeeceseeeceneaeeeeeseaeeeeeseeeeeeeaeeeeseaees 7-4 
Finding all AG ViCesrs.3 2. ccccs cceseastc dovesntedsgotaue te sadetebesadaue dedaceh odes atseavevedes sdaselesscigentdgetesetlannises 7-4 
Callinga device vector ....s:taiiiet seiideieesteiebe dete piestdivdesdetepies dade debehi pda deseideeneaanegnls 7-5 


CONTENTS 


8 Input Output Management ................ccccscccssssssccsscssecssscsecssscsseessscscecssssssssssscsesssscssesssscsssssscesoes 8-1 
Devices anid HES fics ccieiy sioee eis tegs te sitea tie seen Sete sdata iig step ody scenadee sauce dey sdehe eset tevsene a ested 8-1 
Sound ‘file format: states cain Peak pa la pin la ibaeiaobehed 8-1 
ASYNCHrONOUS T/O so seb os San Soes oh do beeak aie 0aY, DSc Dae se I eh Nl oes aoa aa ote ee eh Po oak 8-2 
Asynchronous I/O without error repOrting.........eeeeeeeseeeeseeseneeceseeeesaeecsneessaeessneeeesatessaeers 8-2 
SVNCHLONOUS: LO sees su. osasiedes oxdgstescvepedesbes pbanbeonpeds betes asubees bode Gedepbunteen dedessduprantersdedes sdevauesered 8-3 
Chainto root device ss..s:.cccsceinege sis abe nest edipaee antes ech paive died beeyaens oyeel begindenk epee easy 8-3 
Chain, to‘superclass devices. a.tiec 58 cithediteet ah aided at as oh steel eb i a ee ema 8-4 
Wait for I/O completion .0...... cee eeeeeeseecsscecsseeesseecesaeecsseecsseecseecsseecesaeeesaeessaeesseessneeeesaes 8-4 
Wait for specific request to Complete ........... eee eeseeesseeceseecesceeesseecsaeecseeceseeeesaeessaeessaeeeens 8-4 
Polling: for completion: .2..s:2 atee.i- Bytes hie agate belddoyiested bee depoeniann el egevienbeaadeiess 8-5 
Signalling Completion .................:::csesecsesessoreresseesonenecsonevessenensenensetenseesnonersonevenseneneetenseess 8-5 
Signalling completion by process ID ........eeseeesesescecsseeceseeeeseeeesseecsseesseeceeesesaesesaeessaeers 8-5 
Signalling completion with no reschedule ............escceeccessseeesneeceneeeeseeeeesaeecsaeecsseeeeseeeesaes 8-5 
Adding a handler: sic.e-ssc.g peeiteg.yotegigih teh voewncg geese vovead pees eye dagen Testo egapee eee ey 8-6 
Remiovin & a Wan letsy cx 22 sce ccictiec sek suit cesitest shat octastonk sitter tyst cas ul earache tant sees 8-6 
Enabling a handlets..2::s.vaiewli ncteientedi vinnie tau etal nas alaiewigsataucare. 8-6 
Requestie sa: Feset sess a cess Sil, tar feg ales Rueevet vey dations seat gales Sug eestadeyodeneeerewateddvede Suupvaxtees: 8-7 
Cancelling: a requested reset. .:.: s.vos.osa.pduet eisdelbegipaed Gade dedi plaid des esegapdaneedeyeldaeepiebenedees 8-7 
OPpeNiN Sa GEVICE: wocczten 2. eheak Toeet oes it eet oe ER eek oO a ae at ce a en Sak 8-7 
Closing a:dévices: sicistec hil ei navi ev a ee eee 8-8 
Reading from a CeVICC...... eee eeseeceseecesseecseecseecsseeeesaeecsaeecsseecsseecesaeecsaeesseessneeeesatessaeers 8-8 
Writing toa deVICE 2.205552 Gaye suesiytank epee aanvdonk Geipeekbeeap dees ath eaaedesd depeeldusaeoestdephibesnee eee 8-8 
SEEKING OF: a GEVICE so es hos She the et oho cata See abot cats Siet ok abcd ast tant cos heteroatoms Gestetvint sae? 8-8 
Mouse and keyboard 2:3 s.ve:.ates cava tales ee aith ian ceaieieieiiniausndgaaieicey 8-9 
Adding an application handler ........ eee eeeseecsseeceseeeesseecsscecsseecsseecesaeecsaeecsaeesseeesseeeesaes 8-9 
Removing an application handler ......... eee eeeeeseeesseeceseecsseecseeceseeeesaeeesaeecsaeesseeseseeeesaes 8-10 
Enabling an application handler... eee esceeeseecsseeeeeeeesseesseeceseecesaeeesaeecsaeessneeesseeessaes 8-10 
Getting theishift’states..:::..c4.c.css hs ties cel iin laren bk inn ainn linn nea 8-10 
Wait for I/O completion no handlers 20.0.0... eeeeeseeescecsseecesseeesseecscesaeecsseeesseeeesaeeesneeeaee 8-10 
Requesting a signal from the SUperViSOL...........:::ssccssecesseessseecsseecsseeceeeceseeessaeecsaeerseeenees 8-11 
Cancelling requested signal from the Supervisor ............c:ccessssceceeseecsneecsseessteecneeesseeeesaes 8-11 
Request signal on next half secondo... eeeeeeeseecseessneecseecseeceseeeesseesaeeesaeessaeeseneeeesaeen 8-11 
Query the completion of IoNextHalfSecond ....... cee eeeeeseecsseeceseeeeseecsaeecseesaeessseeesseeeesaes 8-12 
Playing back a sound file synChromousSly.............essesessseeeeseecsscecsseecneeceseeeesaeecsaeecseesnnees 8-12 
Playing back a sound file asynChronousSly............esecseseceseecsseeesseeeesaeecseesneecsaeecseeeeseeeesaes 8-12 
Cancelling playing back a sound file oo... eee eeeseeceecesseecseecsceceseeeeseeeseeeesaeecsaeesseeesnees 8-13 
Recording sound to file synchronously ............cceseceseseeesseeeescessseeseecscecesaeeesaeecsaeesaeeesaeers 8-13 
Recording sound to file asynChronously............cceecesssecesseessseecssceceseesseeceseeeesaeecsaeesseeeaeers 8-14 
Cancelling recording sound to a file... eee eeeeesceseessseecseecsceceseeceeeceseeeesaeecsaeesseeesnees 8-14 
Input Output Management update 0.0... eee eeeeeseeceeneeceeecsscecsseeeesaeecsaeesseecssaeeesaeessaeers 8-15 

Asynchronous partial sound file replay .........ceeeeeceeeseeceneessseeceeeeeesseecsseecsaeeseseeeesaes 8-15 

D File: Manageme nt sccccicecsescicecstccssecsasseosssessasesbaséosesencsosusenssocvsaddsoeebsedsonsbeddsondnsassseeensesoavonssseases 9-1 
TRE ALE: SOR VEL, sas s2ich coset iss 522s Seve ta bos cck Fibs feist basen Big Pete Ses ovd Rana voevd ba Aes cvd Saeanetes 9-1 
Connecting to the file‘serverssissieacstdss.cs.istsceatdsascastisioeatasssass testes atabasoeeleateaeataiaaselas eens 9-1 
Execute-an amie tiles cscs aul sie Gulia ie A Be eels 9-1 
Parse-a-file name is: ssthess deste Asvtitehivtins Anoisbe Ash. ns Aaphesichepions Aativascup cassislaamiers Aneaisins 9-2 
Get Current Path ss sss. cers sieccck siunecudtauis seb saues cvssecbs dub sevbs rodbarie feb sanyesevechvededsteeesesetevesvescevesvecdes 9-2 
Set current: Paths icecs.ssguscscadesesesscesssesseaseoohesascesseaisesbesasseredsassostesendsoddsavevets desssetdsassoata suey 9-3 
Test Path: available si: 265. scchSsegesue ces seehs dckewus cess ceebosehesus Sesetues dele sea ravbevelosesevtacisl Seresbeveasaeh od 9-3 
Deléting:a filer ditectOry...si.:sis,oah sinew alain oun danse ek Baaie A 9-3 
Renaming a file:or directory. sic csss2h oxsevs thus Pesach ws eoes ch sstadeuseusacieosdubeeets buastbethessshackencudstanedy 9-4 
Getting file or directory, Status: :i.:sic:.ce.iishspeciesi.cestestageatasisceteaiapeasensoesles at easaceionelaseseees 9-4 
Setting file or GirectOry Status................:csesesseresesereneeteneeecsonerssevensetenseessonertsevensetenseees 9-4 
Getting: device status. ic. s. levis syiekeseedastvsvdasiseedsaesbeascssadisesvaghuse ovsidessdvasdes usibereserdios se 9-5 
Gettinig’ file System Status... :r03<scs2sv5 eet sess cath ave evb teks eetnebe vl Stans suspsbe delseebentestbe tel cavesenvsabbeds 9-5 
Makarie aie w. directory 2..3caaccetis sass ntasscestastasund sates idecnsendavecestualaseanda toeeieaewestaieesteats 9-6 
Opening a unique file Name: ss. 5 sich sso cess Gets ceke een cece hele denen cave cietb ewe esea eastoetnceeetence od 9-6 
Attaching afile system's. 3.0 Asicss tah Msi also i sitions Miaginaddsees Baaensis sete apbaete cs 9-6 
Detachinga filesystems: on nstietidin piss pisiens dusietiasis desis iisteackudivstin és 9-7 


iii 


EPOC O/S SYSTEM SERVICES 


Get current path: Dy TD 5: 0szccisetesuscuva2vas fins tuys cuusaeveiesdeces fovsteustiagivi colptebstinstnes resadeesdnsteiees 9-7 
Chan SeCireCtOry ss sslatssetesecdustaisesstea acsslasiotetes are eladedstag.ardnda motets aodeedatecatas wooed seed 9-7 
Set mitial Path ci252ch. 655: ceshheistevescecsanels eoteswa resected, sokesuncesdareloactasee eslavehiesbestacgssersnsoeewees 9-8 
Setfile: dates: ic103csevedaoie side tee soist eh tAsshibidiehasien here Aiphial chee As itisiteh ai 9-8 
Local file system Chan ged iss.s0..05 As, cos vaescsves disb ses sck ceca Suvi cueschussusacten covetavesvendyussdeustobsatensvicd 9-8 
Reading media information of a local AeVICE ..... eee eee eeeseeeseeeeseeeeseeeesaeessaeecseeeeesaeeesaeers 9-9 
Reading a local device directly 0.0... eee eesecesseeesseecsscecsseeceseeeesseecsacecseeceseeeesaeessaeessaeeeee 9-9 
10 Process Management...............cccscccssssssscsscssecssccscccsscssesssscscesssscseesssssesssscssesssscssssssscsessssessesens 10-1 
The process ID and names..........eseeeeceeeseeceseeseeecsscecsceceseecesaeecsseecsaeecseessneesesaeeesaeeesaeers 10-1 
Process SCH edule sx -secsten fo. AG cectvct sak caletows tice sah vat oct tncl ant aii oath hae a AON 10-1 
Process controls ss tenth Gus haehs cavis aw ei eave rata yeaa are ates ene 10-2 
Process ID and process table address .0..........sceesesesecsseeeeseeceseeeesaeecsacecseecsseesesaeessaeeesaeers 10-2 
Terminate-and Killens cciccaittcyit aie aipiesd eve daaipieel Gayle tpi ande Pepi eeaes 10-2 
Getting the current process ID... eee eeceesseecsseecssceceseeeesseeesaeecsseecseesesaesesaeessaeessneaeessaes 10-2 
Getting a process ID by name... eee eeeeeeseeceseeessceceseceecsaeecsscecsseeeesaeeesaeecsaeesseeeetaeeesaes 10-3 
Gettin ga PLOCESS: PLOLIEY:.. <s.c.cs.:cehscepssnsesteseetecepsdepeeveachocepadehenttaeubedepstegenbezaabeceyocetenteadsse 10-3 
Setting: a Process Priority 2.o.235 soe caetevecgeyoesdusapdesssoesbegh pte. b eee yoesbesnnivel oyeabesnbdned divbesbecenaiee 10-3 
Getting the OWNING PIOCESS .......... se eeeeceesseeesseecsseecssceceseecesaeeesaeecsaeecseeessaeeesaeeesaeesseeeeesaes 10-3 
Creating-a Process essschiecese teste teesstaraiatcci sands eaten eng alesisoniinn anioaier al 10-4 
Creatit 2a tasks sie, ocsncc vodecea esau cove sets clases votes ateagetg ates s vg adstla eg saetl aged aM pvauts od/odey aig rests 10-4 
Resuming a process.s::.:.ys:daieiestetiyded gees gie de depts deta es baba eteoe eae ae 10-5 
SuSpendin sa: PLOCESS: +9: st eee eh ee he Ae Se ee Re es 10-5 
Killing a process; cs.ssein velit neil an indie aval ii eee iis 10-6 
Re Sisterin Ss terimin ati O01 $2. ¢ see sels sees sceesshs sake beck ecepsdahovegaeshores te sueedeubeceystetenep raubsuyotes sate esehx 10-6 
"Terminating a PLOCeSs sss: ccaece.eeuysceeedly teh becey case daigdes Decoyoews Qigial lesaydessueeneee be supoevsceysuicessnls 10-6 
Paniickiti® a Process 2. cies ices. ois dautvet oo Celndeavtdict ote shct este tnet cts Calas catetectstnatent sitet ee aisles 6 10-7 
Getting a process name by ID... eee eesecsseecssceceseecesaeeesseeecsseecesaeeesaeecsaeesseeeeteeeenaes 10-7 
REMAIMIMG a PLOCESS sh osc 5h siageance tayo ces seg ounce ves aeat thy sfetevedbeesateg olds cant btet bens atta npstotedey ote tenes 10-7 
Finding all processes isi.s5st ieee. teseeeid dapdestcdigdeldevrees tdi ides yiesd oydnebainda ne vonehdennes 10-7 
Watching: all exats-....2 frit. ees al fa asec acetone aaetacnerst stn ets feteso uxt ann ebieteeer ost Sea btatem hetsa 10-8 
Panicking the CUrTeNt PLOCeSS .........eeeeeeeeeesseeeseecscecsseecseeecesaeecsaeecsaeecseesseesesaeeesseeesaeers 10-8 
Copying data from a process by ID ou... eeeseeesecsscecsseeceseecesaeecsseecsseecseeceneesesaeeesaeeesaeers 10-8 
Copying strings from a process by ID ou... cee eeseeeseecsseecssceeeseeeesaeecsaeecseecsneecesaeessseeesaeers 10-9 
Copying data to a process by ID ....... ee eee eeseecsseecssceceseeeesaeeesaeecsacecsseecssaeeesaeeesseeesseeeesaes 10-9 
11 Date and Time Management.................cccssccccsssssscsscssccsscsceccsscsesssssscesssscscesssscssssssscsesssscsseens 11-1 
Absolute ‘and: relative: times. ssi) ss ccus2h; sch seek seech eh asad cocks geuatea Syoe eso seb da ode beak cba otha 11-1 
Waitie: toa Given tHe: ie. cdteash dias bikes sadecedas dosvdiacsedediansascnadiassetedaassvae biases caeties ssa beaees 11-1 
Sleeping for tenths of a SeCON 00.0... eee eeeeeesseecesneeeceeesseeceaeecsseeceeeceeeesaeeesaeessaeesseeeeseeses 11-2 
Sleeping for system COCK ticks ........eeseeescccsseceesececeeesseecseecseecsseeeeeeesaeeesaeessaeeseeeeeneeee 11-2 
Getting the-Systern tare. /2.5¢ 5.) sicist secs sociabs Sodhec soagl enh aataash ees eh a aeadieadegl hae evshe, Sook ahaa 11-2 
Setting, the system time. s.3ssi52.5 sets stisec Aptavieae A eedist aatdens Abstsohessaaisesdasdisiaaseien eties 11-2 
Converting system time to day SeCONS......... ee eeseeesseeesseesseeceeecsseeceeecesaeeesaeecsaeesaeeesaeers 11-3 
Converting day seconds to SysteM tiMe..........ceesceeeessseeesseeceseeeesseecsaecsaeecsaeeseeeessaeeesaeenaes 11-3 
Converting day seconds to date... ee eeseceseecssceesseesceeesseecsaeecsaeecseeceecsseeeesaeeesaeessaeers 11-3 
Converting date toiday seconds: v.0:...4 i s.iis sea fl asiieinh teislep hal teh phbosiies teh carhg 11-3 
Numi ber:of days 1104:nOntlt 3 .2.eseces sis foes cabs2nsecba shes cossteeconsees aduescuy sdeuse obaduuteessubadeostebadensdupade 11-4 
Week: day tiumber. ssi csisiecsstsiiceusdeviossscanccarsanttosssansecsianaanunansvocusenaawrenasouaneseaseteanionee 11-4 
Naine OF day. isi tee.tcecksuattacseactotes ciate leneuckoteniuete Senanehoesuatesees sanchon suateroasenmetonueeneieseugneh otueeee 11-4 
Name of months: :..ccsss hiss Mattes Aeiisss asteessdaoistatin Aseiesi aches Asusbe pion Aaotens are AS 11-4 
Weel numbers <5 os: ses Sones cssteubs fel scevssestaths col stebscutt ie pebsevgscuys beret steuscedbaibesstsdeyerustataeasteveuees 11-5 
Abbreviated: name:Of day s.ssci.sdsisvessgackesadalioeeristacaedaoestasacesadaiaosatactandedaseessancaseonda ieee. 11-5 
Abbreviated nameof month's 055. sigecci Hh hsssd eelooes Sek oeed eshoet sid vel ede tiehea dl oan eiiebeedebedde 11-5 


CONTENTS 


12 Conversion Management ..............ccccscccssssssssscssescsscsecssscseessscssecssscscesssscsesssscsesssscsesssssseseseees 12-1 
Unsigned integer to buffer... eee eceeeeccceeeenceeceseeeeeeeeeeeeeenaeeecseeeeeceeaeeeeeseaeeeeeseaeeeensaees 12-1 
Unsigned long integer to buffer ............ ce ecceeecccceessccceceenceceeeeneeeceenaeeeceeeeeeeseaeeecesnaeeeeeeaaees 12-1 
Tite ger to DUTer x12). sess cce esos eviveces etivecenivege cos sde dedeuivs vededtadeceneeieeeateda dodanie tounsotedeuunevadeeveeteg 12-1 
Long integer to: buffers: iscccc.cisetcesedssdeaseisetecvvdes bedevisah ccavdcadcdevdcabedevdchdcgevddaa cavvecebeaedcvbesendess 12-2 
Convert arguments to buffer ............ceeeeeccceeenceeceeneeeecesceeeeesaeeeceenneeecseeeeesseaeeeeeesaeeeeeeaees 12-2 
String to unsigned Integer ........... ee eeeececeeseceeesenceeeeeeeeeeceeneeeeseeeeeeseeeeeceeeaeeeeseneeeeeneeeeess 12-2 
String to unsigned long integer ..........e ce eeeecceeesnceeceeeeeeeceeeneeecesaeeeeeeeaeeeesenaeeeeseneeeesseaeeeess 12-2 
String: tO INCE SER viscid eveeseceeeccatadsccee ceayd cdbesusdeveedaviesvesaedeseedardesussendeseiderd covidardesvidandcevecnbbens 12-3 
String: to long ainte ger iy. ices seek ah eakeie hak ae eahatce dah GU evi hiek autotest desalted aeredee 12-3 
Floating point number to buffer ............eecccceceesscceeesceeeeeneeeeeeeeeccesneeeesseeeeeeseaeeessenneeeeneas 12-4 
String to Moats vecccess ceeeadiscaecavededaletaceletedeseincedsseiusedesniarecagslotedesbinrecssndetedepadncerenslenetevdans savy 12-5 

13 Long Integer Managemen ................scsssssccsscsssecsscsecsssccessscssecssscscesssscsesssscssscssessssssssesesoees 13-1 
Comparing two long integers ....... cece eeeesecsseeeeseeeeseeeesseeceecsaeecsaeessseecesaeeesaeeeaeessaeessaeers 13-1 
Long iiteger multiplication: ::5::i.:ascsisscesi ca tissangasgsssteastiaovete sinter iditss abeiiaaettansstaeeee iat 13-1 
Lone atite ser division’. iiss feussbissies hock Seesches See taocd bbe g ese Shed ited eesiota its Deus bebiecibii conus 13-1 
Compare two unsigned long integers......... cee eeeeeeseeeesneeeseecseeceeeeessaeeesaeecsaeesseeeeseeeesaes 13-2 
Unsigned long integer multiplication ..0..... eee eeeeseecsseeceeeeeeseeecsacecseeseseeeesaeessaeesseeeses 13-2 
Unsigned long integer division ........... ee eeesecsseceseecesseecsseecsscecsseecesaeeesaeecsaeecsneeeesaeeesaeers 13-2 
Unsigned long integer random numbet............. ee eeeeesseeesneeceseeceseeeesaeecsaeecsaeecssaeeesaeeesaeers 13-3 

14 Floating Point Number Handling ..................ccsssccsscsseccsscscecssscseecsscscesssscssesssscsessssssessssesseeens 14-1 
Comparing two Floats:.::cic2..333 avsvdesepcest iets iedipiesd dats hedepian deb aeyiewb agin ee leeeylenb ged 14-1 
Multiplying two floats ccs aoc ce. elec esceunt ces eicide ce atid cee tewaeda tek sae taesenah Gavetanaedierathaateneeesuuvee 14-1 
Dividing floats: c:3.cccccasectetiedessaricdevsatccievees cevestarcedeschnceuesda covsacaecenvednvcessceaa cenvedaveeseeedeoesea ces 14-1 
Adding two Floats .0........::ccccesscceesssceceeeeeeceesnneeeceseececseeeeeesnaeeeceenaeeeeeeeeeeeseaeeeeeenaeeeeenanees 14-2 
Subtracting Floatsin:. cscs: cg.yeeitusss tess caeyaeltessraestegiyeel behind giyheinesiaeauyebbegedebanyeniaeaeh 14-2 
Nesating:aPloats.:2 iin seats thde aihacuieeted Gited dh Ghee GUM aeee ea lees 14-2 
Convert Float to a signed LOM... eee eeseceeseccsseeceseecseecscecssceceseeeesseessaeecseessneaeeesaeeesaeers 14-2 
Convert Float to unsigned 1Ong...........eesceescessseeceseceesseessseecseeceseeeesaeecsaeecseessneeeesaeessaeers 14-2 
Convert Float to a signed integer... eee eeseeceseeceseeeesseecsseecseeceseeessaeeesaeecsaeecsseeeeseeeesaes 14-3 
Convert Float to unsigned integer... eeeeseeesssecesseecsseecsseeceseeeesaeeesseessseesesaeeseaeeesaeers 14-3 
Convert signed long to Float ........ceeceeseecsseecsseeceseecesseecseecseecsseeeesaeecsaeesseessseeeesaeessaeers 14-3 
Convert signed integer to Float... ceeseeessesssecceseceesseecsseecseeceseeeesseeesseecseecsneeeesseeesaeees 14-3 
Convert unsigned integer to Float.........e cc eesceeseccesccessneecseecsscecsseeeesaeecsaeesseessseeeesaeessaeees 14-3 

15 Floating Point Function Interface.................ccsscccsscssscssscseecsscssecsssccessssssessssscesssscseesssssessssees 15-1 
Aresine: Of afloat sstecetts iit ceadsteccstdaeecsatactcdatathccsatatecsteatecawtactecstaasioauatatisacheatoauatateaeates 15-1 
Arctangent:of a float s:.sii ssf aiid aed io heii eu eter tooled iawn 15-1 
Cosinetof a floatv.ia:scist aa bnii aa ddahi dani an A Aah as a aaatas anna suanies 15-1 
Exponientiation ofa flodtin: 2.5 205.2cescebschusssiadevseutsdivaeetaducctutsciuases sdvestoipcesasuh sduespebackeseus steed 15-2 
Zero fractional part-of-aPloats. ..:33:.s.ascstiveetiseszepia sores ssid deskdataoeetageandayicashonassaniatioastagiagess 15-2 
Natural logarithm of a float... ee eee eesecssceceseeeeseeeesseecsaeecsseecsseecesaeeesaeecsaeeseeeseteeeesaes 15-2 
Losarithin-of afloat iis. a seeihsicsisiiedep sie: Asedassdey dich avsphisscue des nvtde ssccae basi aertaaestebedepdasened 15-2 
Modul o: of a: fl Oat ss ics sets itisces Sauce ceshiths Soniaete Cedaatbe feeaBene Sedhatbe Set sdeee Felacebedersdeneduiboubedunstebesesades 15-3 
Power Of two: Floats’ sais siecssadastedeags acc sadach cdarcaieccvedackedatagecauadastedanaasncaradasedege acercarsoaeaatie’ 15-3 
Float random numbe .............ccccceceeccceeeesceceeeeeeeeceeneececeeaceeeeenaeeeceesaeeeceeneeeeeseaeeeeeeneeeesenees 15-3 
Site Of a FLO Ate As sev; dics bees dacese ds dass tiasvesetaged antes csasete Pode cteanounedageavetscaneetsdafosunoiassetedapssenaanss 15-3 
Square: Toot:of-a: Moat. sree. eccossiekevbs He eskeb adie sevisdevesdbacius adaduectubschensbsduvctdve chvnsidadvocrsisdeerecteavk 15-4 
‘Pani sent :of afloat. ts.: svspsenessateansesas sesdaptenicteseeesaasnteshetuahosssasntoss daustesnsin te pignad assuanee etree 15-4 


EPOC O/S SYSTEM SERVICES 


16 Character Management ...............ccscsssccsscsssccsscscccsscssccsssccesssssseessscsesssscscessssseesssssesssscssesens 16-1 
Character 18a: cit ie ecvsicyssccsats btn eae cxladoas tice aan eelet oad Lest ott aa ietpviems olede eee eited ites 16-1 
Character is a hexadecimal digit... ee eesecsseceseecsseecsseecesaeeesseecseecsaeecsaeessseeeesaeeesaeesaes 16-1 
GHaracter 1s printable sccscgesec sos geves ee gscetsaegaudeuet eves int ses fedstevesdean tet edd ocet eae ninh evuetesodetsteas intense 16-1 
Character is alphabetic. ..c.3:2/ cist assis a de ee ea 16-1 
Character is alphabetic or digit.........e cee seeesccseecsseeseseeceseecesaeecsseesaeecsaeecsaeeseseeessaesnaeessaes 16-2 
Character: is Upper: case. jsscn.ai eine care berin ath as iia hehe. 16-2 
Character. 18 lO Wer CASES v2: ob, eset edocs ee) ents tatedey sees snndedetedesaget sevdeserdent-deadedentp bake. devotee sstg nestle 16-2 
Character 18: space s.ccrasicrsit aiteneayiins Qutdeis dank aereebniaghin sand hen epee agian Gaye 16-2 
Character ds: punctuatlonis so) i680 .cs.sheectect cans beet otee ded ott dastote dndontteet ah aie di eet as Glade ad 16-2 
Character is:sraphicsci.0.:iscrentei aitiar aside tistetae ea Guava alsa eaei ease vdasenrenee 16-3 
Character is: COMO Me. pscecfa, odseetiyoce foe paused Pacet sat gstetededeeetateg stun acd btst ones ltteanepiathenp Muneeiees 16-3 
Characters:to upper Cases. ttc taies tinting hana Pade heii and tomb atain bai atess 16-3 
Characters 10 lOWer Casein aces siite bees cece ats ct oasis see e bith och Uauie coe sbdndees seenb ease chest oma iereensvantea 16-3 
Characters to folded characters ...........cecesescsssseesseecsscecsseecesseessaeecsaeecsneecsseeeesaeessaeessaeeeees 16-3 

17 Buffer Management ................cccccccsscsssccsscsscssscseccsscssesssscscessssssessescesesssscsssssssescssssscsessssseeeess 17-1 
Copying: one buffer to:an other -0:5. cis, Mscbes.dcaesessdves tae ssehise dnp dene veeseaedeaphis duswieassnrdasn Ah 17-1 
Swapping the contents of two buffers... ee eee eeeceesneeesneeeeneeeeseeeesaeecsaeessaeessnaeeesateesaeers 17-1 
Comparing one buffer with another ........ eee eeeeseecssceesseeeesseeesseeceaeecseecesaeeesaeecsaeereneeeses 17-1 
Comparing one buffer with another folded ....... eee eeeeceseeeeeneeseneeceseeeeseeeesaeessaeessaeeeees 17-2 
Locating a character in a DUffer 0.0... eeeecceeesecceeeeneeeceeeneeeeesaceeeeseneeecesnneeeseeneeeeeneaeeeess 17-2 
Locating a character in a buffer folded ............eecccceeeesccceeeeeceeeeenceeeeeeneeeceseneeeessneeeeeseneeeees 17-2 
Finding a sub-buffer in a buffer oo... ee ee eceseeceneecsseeceseecesaeeesaeecsaeecsaeecsseesesaeeeseeesaeers 17-3 
Finding a sub-buffer in a buffer folded... ee ee eeeeeeeesneeeeneecsneeceseeeesaeeesaeeesseeesseeeesaes 17-3 
Matchins.a: wild card buffets. csssc.chises ositnssdasioss ost teste casbissoee teat cssecuspooneiedessaetenesenesay te 17-3 
Matching a wild card buffer folded. ...........eeeecccceeeccceesnececeesneeeceeneeeeecessaeeeeeseaeeessenneeeenees 17-4 
Justifyinie a buffer.:..i.cc3.scaticcetlsesessteaioccaedoviaesteaieteasiaiesetaaiee davasteestaaiacaomtarseentaaacaatanioess 17-4 

18 String ManageMEent ................scccscccccccsscscccssccsecsscsecssscseecsscssesssssssesssscsssssssesesssscssesssscssesssoesees 18-1 
Copying one string to Another .0..... eee eeeeeeeeeeesneecsncecsseeceseecesaeeesaeecsaeecseecseesesaeeesaeersaeers 18-1 
Copying one string to another folded oo... elec eeseeceseceseeeeseeeesneecseecseecsneesesaeeeseeesaeers 18-1 
Convertingastring to folded cosc.0. J: hs eset ede choice son nbtededh soest sana tabteskcotet seep igess chev saiaeeseeiee 18-1 
Capitalising a string yaiiyeie dis atiindiaih av lidicibacni einai din alain 18-1 
Comparing one string with another... eee seeeseceseeesseeceseeceseeesaeecsaeecsseecseeseeeeeseeeesaes 18-1 
Comparing one string with another folded... eee eeeeesseeceseeeeseeeeecsseeeesaeecsneeeseeenee 18-2 
Matching a Wild card String..........eeeeseccesseessseeesscecsseceseeceseeessaeecsaeecseeseesesaeeesaeesseesenees 18-2 
Matching a wild card string folded 00.0... eee eeeeeecesneeeesecsseecsseecsseecseecesaeesesesaeeesaeessaeees 18-2 
Locating a character in a String ........e se eesecsssecseecsseecsceescecesaeececesaeecsaeecsseesseecesaeeneeeesaes 18-3 
Locating a character in a string folded... eee eee eeseeeneecsneecseeceseecesaeeneeeesaeessaeesseeesee 18-3 
Locating a Character in TeVETSC......... ee eeeeeeseesseecscecseecesceceeeesaeeesaeecsaeecsaeeseeeeeeesseeeesaes 18-3 
Locating a character in reverse folded ............esceessceeecesseeesseecseeceseeceeecssaeeesaeecsaeeeseeenee 18-3 
Finding a substring 1 a String........ ee eeeeeeeceesseeceseecscecesecseececeeesaeecsaeecseesaeecseeseneeeesaes 18-4 
Finding a substring in a string folded ....... eles eee eeseeesseeceeeeeesseeceeeceaeecsseeceeesesaeeesaeenaes 18-4 
Weristh OF a Stra ooo. os secsch si oes Leds Sans hick cee te bands ob cash bo Valine ane nhs anh ote cat ga es anid ste aaaea cok eae 18-4 
Validating a SysteM MAMEC.......... eee essecsscessncecsteeceseeeesseecsseecsseecseecesaeeesaeecsaeesseeseneeeesaes 18-5 

19 General management ...............ccccccsscssscssscsseccsscsccsscccesssscscecessssescssssssessssescsssssessssssccssssssessess 19-1 
VersiOn NUMDBELS 24.220 dschess Sakti eos hides elaewelpesedeendivs getaduascestduss deasdeascadedersvtohuateasies 19-1 
Getting the operating system version NUMDBET ............. ce eeeeseseecsseeeeeceeeeeeeesseecsseeeesaeeesaeers 19-1 
Getting the ROM version numbet...........eeeceeescesseecsseeesseeceseeeesaeecsaeecseecseaeeesaeecsaeessaeeese 19-1 
Getting ‘the- System, ECD types: i :.si.cb kien Su esa a ese a eee eee 19-2 
Getting the system cold start reasOM.........eeeeseeesecsseeesseeceseeeesaeecsaeecseecseeeeesaeessaeesseeenes 19-2 
Getting the operating system data SCGMEMt........ eee eeeeeeeeeesneessneeceeceeesaeeeseeecsteeeeeaeessaeers 19-2 


CONTENTS 


Getting: the: country Gata: s3.0.iccs2ssefes iaees fos cdevedees dike neladues Sous tans tes sdbs fous euyscey etaie Sessenusdevatbeds 19-2 
Setting the: country data x.i:.:cs.sistasesndsiscd. pea iaceandanseasteaiac aslosiedeleaineessiasdodetaaiae salethodehadatecs 19-2 
Getting ‘the: O/Sdata::.si4. pie Sialic ed Sool eed Mic ed eae dt 19-3 
Getting: errortext:. ashton soho daha hohe dase baat A 19-3 
DUM y*SCLVICE: 2.5 ins evs sees she cousteess cba tus colsteesssDsahun pala chesecus daa fuyatewsods daa seeadhestevs danse 19-3 
Generic-file name: Parsetic.sisiiccstisioesdaisoeatasiesgeiausiessiedosoutatbresiandostiaueaieaiaauasticasgies 19-3 
Setting deferred modes3.nih hace Hale ae eee hd ee hk tia 19-4 
Notify byitextrsdsctsu A siestsetaessAssdissdenciesh Asutessseseiss Asebias nusdisl a aeitapsentdson Aaadisisarisee Ane tasy 19-4 
Notify: be error: tutm ber 2.3 oi: e2cssr5 iesies saves eau Sbeceh saves Pasha keseud ptuee eas tebested Stubereetcbesten Sieeea totes 19-5 
Hooking the notify miter faces. sic. isdcsspeatacteadasboestes sec aaledouetassceeulahontdauseieasoenaaicaetlss 19-5 
Unhooking the notify interface 0.0... eee eesceceseeceseeesseecsaeecsscecseecesaeessaeecsaeesseeeeteeeesaes 19-6 
Getting systemran: SiZ65, isissicvssde is ueedies Aaziesodhavdens aide ptehi sed aghesdAcebepdaghusi aseiesss edits 19-6 
Getting: the command line. :5.2.5:cces hes sdedvsscede Messed sdyestets deeneubsduesselackeseadstusesebadevacubsteessviss 19-6 
Getting, the:sound Mags. s.s.cc5s1.Gisceiosettsuecetes ova tiashcaudeaastasaseasteais Beandoeaouet sais tesnadenouelasy tens 19-7 
Setting the: Sound flags: ssi Astle GAG eis SA Le eee 19-7 
Making sound with, the: piezo is: -..scscs cies Astin s sethens aavinesae dass Aandebs Abeta Aaohebe ert Antiane 19-7 
Marking: ai process ‘a8 actives ssi. csssciesdeh sieve sessedesiel sivgessiteevasteussinbavhs ivisteyscssanieieacxesevsabe 19-7 
Markin$\a process:as NOD-ACHVE:s::1<.sdssscestestassendayicesteaiasdiadte,tealoceaslorsoeslagiot eas luadovelagustens 19-8 
Getting operating SYSteM teXt ........ eee eeeeseecesseecsscecsscecsseecesaeeesaeecsaeecsseeceeeessaeeesaeeesaeers 19-8 
Getting notify. states: sisi Asis oaks ends doh hihi Baie eae ete 19-8 
Setting notify state. vc. dvi nists ap ites dua tierios deietiaeien cassie awcvsnes 19-9 
Getting the auto switch Off time... eee eeeeesseecsseessseceseecssceceseeeesaeecsaeecseecsaeesseeessaeeesaes 19-9 
Setting the auto switch Off time 0.0... cee eeeeesecesseeceseeeeeecesaeeesaeecsacecsseecssecseesesaeeesaeeesaeers 19-9 
Capturin § an interrupt: tis icdceass desdisedes he iissdiapdeseens Avapte so apdasich solgsbeasdagdeseteantiapseesdaaiel ee 19-9 
Releasing an interrupt 35: chit esses toni da cessed tied Qevslesat abe ielsausea tale eusteussnzcbenet 19-10 
Getting the lan suase code xs. ciiisss.isssecisdasdiedesetasinccegaiaesctessesiateaslowvodelan at eatleasebeatea teats 19-10 
Gettin s:-Sumix texte ccsiscsttsisecil fest ea sok Socks dodeeed Sid ht ciel Severin Hier oe eke ak sesh ek ee sv 19-11 
Getting the amicand’ pm. text). i.:s.si4 esis sida sicptedessdss iesccpsehisodhaphesd isedasodeap busi dpsntesssensdasted 19-11 
Gettitig:the battery types sis... tet. hep tetisioks dusters delete hess cduscts veda dceeisieereiss 19-11 
Setting the: battery type s.iss:.c2.t:cAocsses. sca. pdacseasdaasons sane ceasacedoueies sh Tausaievoselanetaseacenouelgauteds 19-11 
Generating:4: CRE» c.cesieises tei tei seen hi ies oa a asa ogee So sees 19-12 
Interrupt by number ‘4 siss¢ cet issssetiest Aiea Manion Aten Asti A hea Aerie Anes Asti At 19-12 
Getting environment variable... cess eeeeeesneecssceceseeceseecesaeeesaeecsaeecseecsneecesaeeeseeesaeers 19-12 
Setting environment variable... eee esecssceeeseeeesseecsaeecscecsseecesaeeesaeecseessseeeesaeeesaeers 19-12 
Deleting environment variable ........... eee eeseesseccceseeesseecsseecseecsscecesaeeesaeecsaeessseeesteeeesaes 19-13 
Fitidins: environment variable’: 25:55 sciss fide sedetedess desde sdsvtedios Avaeiaas caedios Aaetastdeaedige dese dass 19-13 
Getting string environment Variable ............eseeseessseeesseeesseecsscecescecesaeeesaeecsacersneeesteeeesaes 19-14 
Setting string environment variable... eee eeseeecesseeesneeceneeceseecesaeecsaeecseessseeeesaeeesaeers 19-14 
Deleting string environment variable .0........ ec eeeeeeesceeeseeesneeceeeceececesaeeesaeecsaeesseeeeseeeesaes 19-14 
Finding string environment variable.............eeeeseecesseeceneecsseecesceeesaeecsaeecseessneeeesaeeesaeers 19-14 
Hooking the alarm interface ....... eee eeseeesecsseeesseeesseeeesseecsaeecseeesseecesaeeesaeessaeesseeeeseeeenaes 19-15 
Unhooking the alarm interface ss:.:55.425,s:5.0-esdessodatessoteasiesdodeteaiersstdachosetaassesoaashedabeauio walls 19-15 
Getting the pid of the alarm Server ......... cee eesceeseeceseeeeeseecseecscecsseecesaeecsaeecsaeesseeseseeeesaes 19-15 
Resetting the auto switch off timer oo... cee eeeeeesseeesneeceneeecesaeecsaeecseeceeeeesaeessaeessneeeees 19-15 
Controlling’ Of-EVEN ts. 6205: 25 seis os sSoush eas sh cus set estcns fish subs Haste aciiss ba Pass ewbs divs Das Pasevushust ved 19-16 
Get state for auto-switch-off if mains PreSeNt......... eee eeeeeeeeneeceneeeeteeceeeeeesaeessaeersaeeeees 19-16 
Enable/disable auto switch-off if mains Present ...........eeeeeeeeeeseeeeneeceseeeeeeeeeeaeecsaeeseneeeses 19-16 
20 Database File Managementl................ccssccsssssssssscsseccsscsecssscscesssccsesssscssesssscssecssscscessssscseesssees 20-1 
Fre Str tC ture gsisae gs cieeeey sisi cep hele y Sasa piss echs Soeb dag dsh dee ydive Sapte egh dead egapashblaiebeek depen aey 20-1 
Butera 853 oe 2 42 coectae sek at cot tise och eabat od taeak Saha eh tet Sah ceo a tect deh Me ht a ai oh eat ee 20-2 
Index Tablesssvacichtas. teva iateeicavai ales caval nel asiavainni auravginel anmeraieeieines 20-2 
Bindi Ob le TECOrd go. sso ie fade tte carhtegetene eds tat tee adeete foeat ete gadoanegeeat Mi vadeatye peat tevalobereest ete 20-2 
Number i6f records siz: c.s3cccgydest caeeeesbetigdasbeeesbes hadi dasd cay beebdi pus ete gaged Gad eepae eee 20-3 
Opening @ database filé.isc¢.30.2 set an ee eee eis Se al eM oe ae 20-3 
Closing-a database file,::..iinestinciiinivieh avi suite navel ein ie ieee: 20-4 
Flushing a database file... eee eeseceseecssceceseecesseeesseecsseecesaeeesaeecsaeecsseecseesesaeessaeeesaeers 20-4 
Trashing: a database file. i.:cs:2.sccne.ccaeycaitesspcestegeyseibeshdesdegiyeesbegieaesbgeyighnusipivel eeyleibisiydne ell 20-4 
Copying :down:a' DBF record 08 aul shiteet te eed tie Se ccls tee ae inde ee te ail 20-5 
Compressing a database file... eee eeeceesseseessneecscecsseecsscecesaecesaeecsaeecseeesneesesaeeesaeeesaeers 20-5 
Copying a. databasetilesss st ssastecleocessecesantevevesseses estat etucetsascedeans athe edesbvepnietethressueeeprens the ets 20-5 
Getting the:sizé.6f-a DBF..2:.:cc..:0.c:indiigsish ni iia piste iba liben i aeplnnien dies 20-6 


EPOC O/S SYSTEM SERVICES 


Reading a DBF extended header... ee eeseeeseecssceceseeeesseeesseecseecsseecssaeeesaeeessneeesseeeesaes 20-7 
Writing:a. DBF extended! header ts:..2:c.scs.tsesatisecs denies teanesalanwsdsieaines alae ane stactoeetans 20-7 
Reading a DBF descriptive record ..........eceesceseseecsscecssceeeseeecsaeecsseecseecsaeeesaeeesaeessneaeeenaes 20-7 
Writing a. DBF descriptive Pecord : :...ies2ccsceselapbesat ta ssersp deasvastdasvovanbebeaeidaaveeaphestesriaabcasate 20-8 
Getting the DBF version numDe?.............eeeceeseeeseessseecsseeceseeessaeecsacecseeseeeeesaeessaeessneeeees 20-8 
Reading an absolute DBF record ...0..... ec eeeeeeeecceeneeesneecseecseeecesneecsacecsseesesaeeesaeessaeesseeeees 20-8 
Reading and sensing an absolute DBF record 000.0... eee eeeeeeeseeesneeeececeeeeeseeeesaeessaeessneeeses 20-9 
Read ithe: next. DBFTecord oss. sisptdsk os tonasccapdess oes basessesessdeap bbs} savdeseduaebisisuswieresoveast aed 20-9 
Read the previous DBF record... eeeeessceesseesssceceseecsseecesaecesaeecsaeecsacecseeeesaeeesaeessaeers 20-9 
Read the:first: DBE records :::ci.sgsisscsssasicsssdaiancenss cane andaceabasiarestdaiapeenas Apeskbascanbancaosendauenss 20-10 
Read the last, DBE Tecord:y:).. ssi seis Sik aie hi eel cig ei ole asil elie Seloaates 20-10 
Append ‘a DBE tecord: .. 3, sce resides ices astde dessa debieses tages as Natsetedalbsssbibbeete asi antares eee hte 20-10 
Brasin ga DBF record 2:3 sctsiiovs ts fe.Seubtaiwsrits savieubstieseebaduescuistavssidashen calsteesssbsduanssssdeessevs Beets 20-11 
Updating a,DBE Tecord ws.:s2ccsscsileseiawteusiisichisuee esis ats stn etatisanantsitatiaeeen ated 20-11 
Binding BE f6COrd ss iiii ty cout csl shes Wien tasd ofsh ocho aed Seuss ies oekaki dod Pe ego bach 20-12 
Sensing the current DBF record numbet............ceeeeeeseesseeesseeeeseeeesaeecsaeecsaeecsseeeesaeeesaeers 20-13 
Counting the number of DBF records 0.0.0... eeseeesecsseeesseeeesceeesaeecsaeecsaeecsseesesaeeesaeeesaeers 20-13 
Eindine: aDBF record by feldissasc.tsstccwteiieistsstaceladocstdnaaeatamodatissoeedateeaticasedateeds 20-13 
21 Hardware Management ..............cccscccsssssscssscsesssscsscssssccessscssesssscssesssscsessscssccsessssesessssscseessoees 21-1 
Switching: On the COMBO 1... foie, svesees lee edetevde seuss poanteaeseant seoyoret eves saateveyoees te steteeeeaesy tet 21-1 
Switching off the CombOe.3::...2:.. eo staiieicnviaharin en iii densi lanianente 21-1 
Switching onthe SSDsei0 niet AA BAe Rl ea 21-1 
Switching off the SSDs: 2. sche nie sevhes elie eh ei evi wh aie eed eed. 21-1 
Setting: bits Asic2 TESISter Lost .fc,ssus coyeths svie vaste dey odes steesaetevevs des sveysgntevadetil oveptartovegetesouepnast es 21-2 
Clearing bits Asic2 resister 1 ii:..ccccyseggreestsindev cee yigsagey bobede pies Deesuaesbedaphestedeydenbedevecbdecs 21-2 
Reading: Asic2 Tegister ] ai ti ieee se autodata deed odevinad dee ate Mano ato din tes ahetode ih 21-2 
Writing Asic2 register] scsccccssiseccessesecesscceeceanceea ceanccas coandevedeanccosceandeavdvancdaecsaa deveduaurcesees 21-2 
Settings its ASic2-TESIStEr Diorio fesrdevcs oxng sats vtetexe posts santas ietenksedessseydinbesupeeseeuepeedeeeseeuepeeeenant at 21-2 
Clearing bits Asic2 resister 2 s.2:1.sce.dnraeieaeisten reste eed neds oissbeaanieeleddeebaeetds 21-3 
Reading: ASic2 Tesister Qe asec cy sc. sect sane viata choad sons suhgesh sheet ogee sunguendovst eave sougess Gveteaeesttoab ate 21-3 
Writing Asic2 resister:2:s:c.ves eh eee civ Rie nia os Rie ee Ri eines 21-3 
Setting: bits Asic2 resister’ Soc sls, 5s0 ste poses esis santa desetenseepbdeseesedou sce sintesapedesbanp idutetscedetonsptent ys 21-3 
Clearing bits Asic2 resistér:3:.s2c.csccydesteustcesuegiedesnedesecibaeoydesbenspiehbessedesbedipiaeleseydewbegeauibecs 21-3 
Reading ASIC? Tesister.3 .i5.3 ces cactus sek ae onesies aah auton teal aed aut ati thetsh aid teeta wood aty 21-4 
Writing Asic2 register 3\s:ciceieieias eaves Gi eaieie Aa oe inion Sia se liel data res oaies 21-4 
Selecting. a:serialchammel’. so. .sessscledlodes si peandscevotes we dstate Avedsusce paints Miedesecepssage Ageteeeegniet sk 21-4 
Sending a‘serial null frame. i..5:.2 scsevtegepist aendestegegdesd des beled abhesbedes beds poesb aden deeopoee inne 21-4 
S Within G Off ..5 216k urs tives het eat det eh d het ited Retna hd hot ee itted ats 21-4 
Exitin® to: DOS sivaiiesi seis evs near i i aval ei 21-5 
Capturing the Combo subsystem ............s:ccssscessseecsscecsseeceseecesaeeesaeecsaeecseecsneecesaeessaeessaeers 21-5 
Freeing the Combo Subsystem ............seeeecesseessneecsscecseeceseecesaeessaeecsaeecseecseesesaeessaeeesaeers 21-5 
Grettitig a Channel sie ec lstce ooo aetnet 5k eb owas thoes canter Sask ctn  Rindadis se cae cithouth tah cee cahebeats weeks 21-5 
Freeing a: channel \e.i03 icnveste ioe rav asic ei ova Saou nerd wh asiseviihi Shiai al 21-6 
Getting the power SUppLy type .........eeeeeeeesseessseecsncecsseecsseecesaeeesaeecsaeecsseesseesesaeeesatersaeers 21-6 
Getting suppliés status...22.55.2cnce-tcsedeibvincestediedelbeuipdestiaey esbedipdasdedesovbeaipdae ceoviehbesvand he 21-6 
Getting supplies Warnings ............ceeeceeeseeeeseecsseecscecseecsseecesaeeesaeecsaeecseecseesesaeessaeessneers 21-6 
Changing the LCD contrast: :2s.tsscheai iis nren wai ar nianntesi avni iain oueieare. 21-6 
Getting current LCD contrast .00.......ceeceesecessseeeeneecscecsseecsseecesaeeesaeecsaeesseeceeesesaeeesaeeesaeers 21-7 
Setting: backlight: control v2.2. c.2.ccysvegi in esevoee gaye ae bdiphobenrel ao ananilenyaniene 21-7 
Getting backlight comtroly 3 soe. ccteet ak ih ecevtiee ah dill emsiod ait eaiteiees aid aed se ai ens 21-7 
Operating ‘the backlight j2.is:s..cs.ces sets ratenceh die ssi ees ceedsiene euneneianeet een tevesavee teen: 21-7 
Scanning Statevor-all KEyS ej osacFevesecsedeeah caeut vey otesaeh epist tesedessde ppiotedapoteeeeegest teticeent 21-8 
Switching on the combo in input MOdE.......... eee eeeeeesseeesneecsseeesseeeesaeeesaeecsaeecseeesteeeesaes 21-10 
Getting additional power supply data........ ee eee eesccsseecesecceseeesseecsaeesseecsseesesaeeesaeeesaeess 21-10 
Hardware Management update... eee eeeeeeseecsncessseecsseecesaeeesaeecsaeecseecseesesaeeesaeeesaeers 21-10 
Reset the ‘battery Status. 4... cse.t.cc) secede scetevny scet sate deetecepaceseath bextedesecensntedabedepateesatessebes 21-10 
Enable/disable reset on recharge...........eseceescesseecsseessseecsseeeeseeeesaeecsaeecscessneeesneeeesaes 21-10 
Return battery information .............ccceeeccccecessneceeeeeneeecesnneeeeseneeeceseneeeceeeeeeesnaeeeeseaees 21-11 
Relog the: SS Dsixcvveseisia naive Sieh hih Ganinnias cots nai ee atal 21-11 
SETHE IR power LEVele., cscs. feces stapsswecveposntevegsisuc degen sees sateen ppiutedepsleteds pouet aie podtseverees 21-11 
Sense the current tick COUN... eeeeseceseeceseessseeeeseeeesseecsseecseeseeeeesaeeesaeessaeesseeeee 21-11 


viii 


CONTENTS 


Sense the expansion port state ........eeeeeeesssecesneessseecsseecsseeceseeessaeecsaeecsaeesseeesseeeesaes 21-12 
Enable Honda connector power ............cccssscccesssceeeeeeceeeeseneeceseneeceeseaeeeceenaeeeseeneeeeeesae 21-12 
Disable Honda connector power ............ccscccccesscceeeeenceeeesnneeceesneeeeeseeeeceeeeeeseeneeeeeeees 21-12 
Appendix A Interrupt and Function numbeTs ...............sscsssccssssesssscsssecsssssessssscsssecssssessessssssones A-1 
Writ OMUCHOM 2-55 fs seis: Sosa Teu sesh Avs cous Te bos in3 Thus Paks 2s Succes Dive Fasg te busoes dese euigte So cous esa fensteds fond eaeeeiaees A-1 
Alphabetical list of fUNCtiONS ............ceeececeeeeeeeeeseeeeseeeceseaeeeceeaeeceseeeeceesaeeesseeeeeeseeeensnees A-2 
Numerical list of fUNCtIONS «20.0... lee eeseecneesssceeeseeeeseeeesaeeceecsaeeceseecsseeceeeeesaeeseesesaeeesaeers A-14 
Additional Interrupt and Function numbers..............:ccccccesesceeeenceeceeeceeeeeeeeeeeeeeeceenneeeenees A-27 
Alphabetical list of extra fUNCtiOnss .............ccceeeccceeeescceeeseeeeeeseeeeeeeneeeeseeaeeeseenneeseeeeess A-27 
Numerical list of extra fUNCtIONS....... eles eeeeeeesseeceeeseecseeceseeeesaeecseecsaeesseesstaeensaes A-27 
Appendix B - Environment Variables ...............ccsscccsscssscsscssccsscecsssccesssscssesssscscesecsesssssseesssscsoes B-1 
PIB ss tcisticiesdset Asis teks eshast iter oeet eisst Asie sashist Adv ashe anes dead aaote Aaveis ooaatsbsphe iba aie B-1 
IMIS vies peti ove ets Fe gett etic coat ahi pautate ores teste naeitteoctenn datas Assad neeate sven Aeaartaatese B-1 
Willdow: SERVER sc cssd5 taht seadetsseasdastasscadeeaseene heat daaabeasasthasthad eae eae nistebdeasd gs Socal esos B-1 
NN {syd e) Bares area ee cer ere tere Pear are Pen eh sre i ete Deep none eee oe ere RE B-1 
SWSCEND Se caties teenestertetees Aereeidntnes herein Ante Retr tlt toas Boots Litas! SANS L oe, B-2 
WS 1B oeroceeact sess ote steveast favs scuvhctles dec vce Pace scuraeee nA stevsteveet ieheh d saeuscevasthe dha storms devas B-2 
SWSaSDDh so titetosstcatantactucatosstas attests teatiataceenteosleceaea tate tee utats oad antacs B-2 
$SWS_SF, $SWS_SF2 and $WS_SF4..0....cecceceescesceeceeeeseeeeeeeeeseeseceeeceesseeeeeeseeeeneeeeees B-3 
FIWIM Gy is daciisdahm addin lhoh nase hinisidteia heii sien Ash sions Asineebeh ted dAotss B-3 
IGN. gecs etre ces teh astcss ease h ost. ca Meseeet eects Pe steve wee ia ha speivtentadhussen teeters sissnets tee B-3 
| DAD, Gainer a cent rrea creer rere aceecee erorerteceercee eorerertcrr cer orca cerca tere eer eee B-3 
Ti Dee sees os coheeof hate ctate oe ot eee yo eas haart veut neat) tfact soot nereeast anc thet Sec uats oes oe shie va ceaa hse eu he B-3 
Paina ss Ses oesi pentose sencceacovutessschavsiascasthsdeseaesiascvaasesdeaovans cass ideas sanvens ovstoeessesueiusoesetiespeaneies B-4 
PED saree sitel Pesce ANSE A tees eth h.t Saas cok ANSE A Pays cuthathe nt Dass cuts Atea Sau. chk at Dns naa B-4 
PGE: stecetes cctactatascataceuntastcsnas sccuatastoatcataceutamocergaesscuetawioseucateacunt aceantaassereatan cantante B-4 
PG Sees ercvesichsteicee rs ccectitesccunen sect ee ance ce cect ars aveene neh tases athe oc tatt si abharct meet See ieee s B-4 
| EAN WY epee seen ee eicter nen teeter Perera rar irene cern eerie cheer rarer tetera reer B-5 
PSP sscesavtesiei ich ester, woreda shes cate F cons ta deen culets csests ihe neatede ceeds teen eetei ese Musi saeite oe tease tee B-5 
PGP P sicz3tsieots ete teritirtrie tas iene tenes tei Malic bets ehes Salactnas ater te nha tslatat tata ian ssi teast ts de B-5 
BGS Beets scoecer St Vaca oot ue areas tise c west orees bent teen ccna behets taceaer tose aaneneceenc bese aee et B-5 
DG Zitsscs een het heres a tock Rte tras Bata Aa tet Rik ates’ Reeece kate Meno bate Nest B-5 
JENS Lape prec Rene reser ir reer eter teerrre ree rer error are ercrer ees tape peter eat cape peters oerte ere errr re rer B-5 
PSP Rech sistecsts ecstasicontatesctstee tates tistvcnateaact stata tate ctueatsestiatucta Medes tit B-5 
Calculator appl cation sj ssh desc. cee odsdescves con ods deteven ene ele tovenee Housel weoea eoustehydemewaceeieng B-6 
CSCALC@ stent teahancasih onan asa cA souiAsnaauncasuinens B-6 
MS0MO to MS$9M9- «55... eestiieias das iesdise hs da jiadier ds daria Saasseideras Aare tee B-6 
FIps:appl CatiOnss-cisseicestiatvoost iscsoestcaieteas se tusaste states tietupsataa ites tea ioeeateaeoosiatepeansagsoossiateoest B-6 
DEW DG ese cete tes tt tate Ge ag Ot Caen a autres RUD Crecente oat ae a Ete B-6 
World appliCatiOni:sdccicscoistisssdesctasosetiads ehssvanbaacdetoddesdvanddasdedoueba casa sahedesesdasduaasansseancizades B-7 
NW SG sch Soret races cus oe Soe ce eet d cae real evades Devs sey abies Seva tata ses devs dey besa eve tevsdesadees RSUITS B-7 
WSRixtoliscstcteteteisteatuts estes tue latatcatia tunes tse, eslaattete a testaataeles. ti stac teins costs B-7 
Spell/ THESAuUrys. sis :sccss tesecevsscuevel sane coevsscseves seuacouss dovewss oesv be cevedeacsoetels svuacousyseceede suuesen seutens B-7 
SPSDRV Gace Arsh A ciate Asati aiti a aisles tetat manana aan B-7 
SPSOBM 2 tes. A ectitas do isit as Aetna hh oie tak B-7 
WIPSSPEL pies stsitouscsccuctssoseisauencacss oul Usa tesa aaa aaa A oa B-7 
Ad BAS Bs | Bhs Sonera caer pe eee ec ear pare See oe ee ey ee ea B-7 
SHAax-ApplCatOnis Assas0h stiss Asstestsshisss Aestesieeatioss Avs teulasthins becsesia sides faetiein sehen heedessees B-8 
| END, Geese eye ener eT eee eee ET CEE Tere eT eee TECIe ner ST Sop UTer ter cay epee Cerrar nee trr creep B-8 
EG MMseccesccontecsscstcputatecctistetutetnastitvcnatsestitaaate tes tetua nats lnstistaat Be des ttt B-8 
FG Pe as Sees eee ect ae eh Cnt Be veoh a EY set aed ets Re tite ty oie eet recat Sou caahares B-8 
Email-applications: 9 ssi.:Assieidbevdies Mache bohardios Asptasshoeions Asi aaiaedse Mei taaiaaeten Aes nade B-8 
MATESS? sc. traits Adarand easteeen Mie wens dase eer ee ee B-8 
Work abouts: sic cstssiies,teaicsascessoestessatsasictvaseleseesavcichovediasne aicslheca huang asgausnestdane abastbocetenet B-9 
SDS VE Reset ert Leet vaca Scoot atte Ned ct Uh Ste Sach eet ge aiid eae ae os Lat ae hat oltre Ne B-9 
CHP Oise SA Ch tiesit sates causttans ts cacancousteane east enipua testes ic anicustiises serine eee aaa B-9 
CSPA10. COPZ asics Abi fiecs cost HAGE sees cess aloe peeeseenatve td Siesta Het Sheets ed os ets B-9 
COPE acces lat Mitac etitecstar ea tatnatiatac sts sstds aa tsna cinta aPstes tastae ta Mestes. tart B-9 
COO arin atone neem ence MATE Ie B-9 


CHAPTER 1 


INTRODUCTION 


This manual describes access at assembly language level to the services provided by the EPOC operating 
system. Access to these services is also supplied by the C function calls described in the PLIB Reference 
manual. 


System services 


All access to the services provided by the Epoc/Os is through the 80C86 software interrupt function INT 
XX. There are two flavours of interrupt services as follows: 


e Single service. 
e = =Multi service. 


The single service interrupts are provided for commonly used services and those services which need to be 
executed with the least overhead. 


Single service interrupts 


These interrupts are invoked as follows: 
INT XXH 


where XX is the interrupt number in hexadecimal. 


Multi service interrupts 


These interrupts are invoked as follows: 


MOV AH, ZZH 
INT XXH 


where XX is the interrupt number in hexadecimal and the ZZ is the function number of the service 
required, also in hexadecimal. 


It is worth remembering that all multi function interrupts will require the use of the AH register. 


ee a 
Calling conventions 


Regardless of whether a service is through a single service interrupt or a multi service interrupt the same 
calling conventions are obeyed by all services. 


e All registers except AX are preserved, unless they contain return values. AX is always assumed 
to be a scratch register by the services. 


e If aservice can return an error then it will signify an error condition by setting the carry flag. 


EPOC O/S SYSTEM SERVICES 


e If a-service returns with the carry flag set then the error will be in the AL register, and any other 
registers which would normally have contained the return results will be indeterminate unless 
otherwise stated. 


e = The error value returned in the AL register will be negative. 


e¢ Under normal circumstances processes will execute with the DS,ES and SS registers all pointing 
to the same segment. In this case the information regarding segment, register pairs in the 
documentation is irrelevant. However if this is not the case then the documented segment, 
register pairs must be obeyed. 


e The services provide access to resources through handles, which are 16 bit integer values. All 
valid handles are guaranteed to be positive, non-zero, and even in value. 


e Handles are passed in the BX register wherever possible and return values are always in the AX 
register. 


e The state of the direction flag is preserved by services and can be in any state prior to calling the 
service. The interrupt flag is preserved by all services and no service enables interrupts if they 
were not already enabled before the call. 


e If a service is called with an argument which is programmatically incorrect then the calling 
process will be immediately terminated. Many services do not return an error. In these cases it is 
foolhardy to rely on the setting of the carry flag, as it is indeterminate. 


e Where a 32 bit value is required in a register pair the register pair will be shown as XX:YY. In 
this case XX is the most significant word and YY the least significant word. 


eee = ——————— | 
Documentation conventions 


In the following chapters, the documentation conventions are as follows: 
e A shaded bar marks the start of the description of a service. 


e Within the shaded bar and on the left is the name of the service. Single service interrupts are 
indicated by being preceded by a bullet point. 


e Within the shaded bar and on the left will be seen the I symbol. This is to indicate that the 
service 1s available in Version 3 and upwards. These services are also supported on the HC but 
may do nothing. 


e Within the shaded bar and on the right is a short description of the service. 


e After the shaded bar follows all the registers which are input to the service. If there are no input 
registers this will be indicated by the word None. 


e © After the input registers description will come the section on return values. If the service does not 
return a value this will be indicated by RETURN: None. If it can return a value but not an error 
condition then RETURN: will be followed by the output registers and a description of their 
contents. If it can return a value and an error then RETURN: Carry clear will be followed by the 
output registers and a description of their contents, and RETURN: Carry set followed by the error 
returns. 


e = After the return values will come a list of the panics which could be generated by the service. If 
there are no panics then PANIC: None. will be shown on one line, otherwise the panic list will be 
enumerated. 


e After the PANIC section follows a description of the function of the service. 
e Any constants, structures or macros which are in include files are shown in the mono typeface. 


e Where a 32 bit value is required in a register pair the register pair will be shown as XX:YY. In 
this case XX is the most significant word and YY the least significant word. 


1 INTRODUCTION 


Include file epocdefs.inc 


This include file is provided to ease the task of coding in the JPI assembler. It contains the interrupt 
numbers for all the services available in the operating system and equates for the offsets for many of the 
commonly used structures. 


For multi service interrupts the name of the service to place in the AH register is as recorded in this 
documentation prefixed by Nm, and the name of the interrupt is XXXXManager, whereby XXXX is the 
multi service group. Thus to call the prockill1 service (where Proc is XXXX): 


mov ah, NmProcKill 
int ProcManager 


The single service interrupts are just called by the same name as in the documentation. Thus to call the 
StringCopy service: 


int StringCopy 


CHAPTER 2 


SEGMENTED MEMORY MANAGEMENT 


Memory segment names 


Segment names are zero terminated strings of up to eight characters followed by an optional period and 
three further characters. Examples of valid names are as follows: 


e NOTES 
e NUMBERS.DAT 
e DATASEG.01 


Paragraphs 


The size of memory segments is expressed in paragraphs. 


A paragraph contains sixteen (16) bytes. Paragraphs are also used in setting the value of the 80C86 
segment registers CS,DS,ES and SS. 


The maximum amount of memory which can be addressed by the 80C86 is 10000H paragraphs, i.e. 1 
Mbyte. Thus the highest addressed memory in the 80C86 is at paragraph FFFFH. 


Permanent segments 


Associated with every segment is an access count which allows EPOC to determine the number of 
processes which have the segment open. As long as a segment's access count is non zero the segment 
cannot be deleted from memory. 


Creating or opening a segment will automatically increase the access count, while closing will decrease 
the access count. In order to avoid a call to the segDelete service, the operating system will automatically 
delete a segment when, after a call to segclose, the access count is zero. Thus create followed by close 
will result in the segment being discarded after the call to close. 


In order to generate a permanent segment in memory it must first be created and, while it is still open, i.e. 
before the call to close, the segLock service must called. This simply increments the access count so that 
after the close the access count will not be zero and hence the segment will not be discarded. 


To remove a permanent segment, the segment must be opened and then a call to segunLock must be made. 
This will decrement the access count so that when the close is requested the access count will fall to zero 
and the segment will be discarded. 


EPOC O/S SYSTEM SERVICES 


a a ———EEEEEEEEe—s 
Directly accessing segments 


Although the segcopyTo and segcopyFrom Services are provided to allow access to memory segments it is 
often necessary to manipulate the data in the segment directly. The following code fragment can be used 
to gain access to a segment's base address. 


GenDataSegment ; Get the o/s data space in ES 

MOV BX, SegHandle ; Get the segment handle 

MOV ES, ES: [BX] ; Get the base of the segment 
peer ; Access the segment 

Gist, ; Disable interrupts 

PUSH DS 7 Save a copy of DS 

POP ES ; Recover ES 

STI ; Re-enable interrupts 


Once the segment register is loaded then the operating system will keep it pointing to the right place even 
if segments are moved around. If the segment is bigger than 64K then the base of the segment can be 
added to in the following manner assuming ES has the segment base loaded. 


CLI ; Disable interrupts 

MOV AX, ES ; Get the value from ES 

ADD AX, somevalue ; Adjust the base value 

MOV ES, AX ; Put the new base back in ES 
STI ; Re-enable interrupts 


Of course DS can be used as well as ES. 


In both of the above examples, interrupts must be disabled while the contents of the segment registers are 
being changed, as a pre-emptive context switch may occur and the segment that ES was pointing to could 
be moved. 


SegFreeMemory Size of available segmented memory 
None 

RETURN: 
AX Available segmented memory in paragraphs. 


PANIC: None 


Returns the amount, in paragraphs, of currently unused addressable segmented memory. 


Since the memory in machines containing more than 512 kilobytes of RAM is bank-switched, this 
function will never return a value larger than 32768 (corresponding to 512 kilobytes of RAM). 


The value returned should be treated with some caution, as the amount of available memory, in a multi- 
tasking environment, is a dynamic function of the memory requests of all the currently running processes. 


SegCreate 


2 SEGMENTED MEMORY MANAGEMENT 


Create a memory segment 


AL CreateSegment Low - allocate in low memory. 
CreateSegmentHigh - allocate in high memory. 
CreateSegmentDevice - allocate in device memory. 
CreateSegment Locked - allocate in low memory but do not log 
ownership of the segment. 
ES:BX Pointer to the memory segment name. 
CX Initial size of the memory segment in paragraphs. 
RETURN: Carry clear 
AX Memory segment handle. 
RETURN: Carry set 
NoMemoryErr Not enough memory to satisfy the request. 
NoSegment sErr No memory segment handles are available. 
ExistsErr A memory segment of the requested name already exists. 
NameErr The requested name is invalid. 
PANIC: 
PanicSegl Requested size was negative. 
PanicSeg2 AL was not one of CreateSegment Low, CreateSegmentHigh, 


CreateSegmentDevice OF CreateSegment Locked. 


Create a memory segment with the name and size requested. The memory segment created is not 
initialised in any way and will contain random data. 


The create service returns a handle to the created memory segment in the AX register. The returned 
handle allows access to the contents of the segment using the segCopyTo and SegCopyFrom Services. 


The memory segment is automatically opened after being created, and should be closed when no longer 
required with segclose. If the process exits or is panicked, then the memory segment will be 
automatically closed and if the resulting access count is zero, then it will be deleted by the Supervisor. 


The initial size in CX must be positive, (i.e. in the range 0000h to 7fffh). No single memory segment may 
be greater than 7fffh paragraphs in size. AL determines the method by which the service will attempt to 
allocate the memory segment. The methods are as follows: 


@ CreateSegmentHigh will result in the memory segment being created above all other currently 
allocated memory segments. All other segments will not be moved in response to this request. 


@ CreateSegmentLow is provided for future expansion and currently has the same effect as 


CreateSegmentHigh. 


CreateSegmentDevice will result in the memory segment being created between all other device 
segments and the normal segments created using the above two parameters. This will result in all 
devices being held while memory is moved and then resumed. All normal segments will be 
moved up in memory to make room. This service is called by the File Server when loading 
dynamic device drivers and should not be used by normal applications. 


CreateSegment Locked 1s the same as CreateSegmentHigh with the exception that no process 
owns the created segment. Like createSegmentDevice this parameter is used by various kernel 
services in the operating system and should not be used by normal applications. 


EPOC O/S SYSTEM SERVICES 


SegDelete Delete a memory segment 


ES:BX Pointer to the memory segment name. 
RETURN: Carry clear 


Success 

RETURN: = Carry set 
NotExistsErr The requested memory segment does not exist. 
InUseErr The requested memory segment is still in use. 
NameErr The memory segment name is invalid. 


PANIC: None 
Delete the memory segment identified by the name pointed to by ES:BX. 


If the specified memory segment is open to any other process, an InuseErr will be returned. 


SegOpen Open a memory segment 
ES:BX Pointer to the memory segment name. 

RETURN: Carry clear 
AX Memory segment handle. 

RETURN: Carry set 
NotExistsErr The requested memory segment does not exist. 
AlreadyOpenErr The requested memory segment is already open to this process. 
NameErr The memory segment name is invalid. 


PANIC: None 
Open the memory segment identified by the name pointed to by ES:BX. 


The open service returns a handle to the opened memory segment in the AX register. The returned handle 
allows access to the contents of the segment using the segcopyTo and segCopyFrom Services. 


The Supervisor keeps track of which memory segments are opened by a process, and if a request is made 
to open a memory segment which is already open, the error AlreadyOpenErr Will be returned. If the 
process terminates before closing the segment, the Supervisor will close the segment on behalf of the 
process. 


There is no limit to the number of memory segments which may be opened by a process at any one time. 


SegClose Close a memory segment 


BX The memory segment handle to be closed. 
RETURN: Carry clear 


Success 
RETURN: = Carry set 

NotOpenErr The memory segment is not open to this process. 
PANIC: 

PanicSeg3 BX is not a valid memory segment handle. 


Closes an open memory segment by its handle. The handle must be one returned from the segcreate or 
SegOpen services. If the memory segment was not previously opened by the process, then the service will 
return NotOpenErr. 


2 SEGMENTED MEMORY MANAGEMENT 


SegCloseLockedOrDevice Close a locked or device segment 
BX The locked or device segment handle to be closed. 

RETURN: None 

PANIC: 
PanicSeg3 BX is not a valid memory segment handle. 


Closes a locked or device memory segment by its handle. 


This service is used by the operating system to manage segments which are not owned by any process, 1.e. 
a permanent segment left locked or a device segment. 


The difference between this service and the segClose service is that for segclose the segment must have 
previously been opened with segcreate or SegOpen, whereas for this service the segment does not need to 
be open. Thus, closing a segment which has not been opened will decrement the access count, making it 
zero which will then delete the segment. i.e. this service is short hand for calling segopen, SegUnLock, 
SegClose. 


SegLock Lock a memory segment 
BX The memory segment handle to be locked. 

RETURN: None 

PANIC: 
PanicSeg3 BX is not a valid memory segment handle. 


Locks an open memory segment by its handle. 


The handle must be one returned from the segcreate Or SegOpen Services. There is no limit to the number 
of times this service may be called, but it must be balanced by an equal number of calls to the segunLock 
service. 


SegUnLock Unlock a memory segment 
BX The memory segment handle to be unlocked. 

RETURN: None 

PANIC: 
PanicSeg3 BX is not a valid memory segment handle. 


Unlocks an open memory segment by its handle. 


The handle must be one returned from the segcreate Of SegOpen Services. There is no harm in unlocking 
a segment which is already unlocked although, if this is done inadvertently, the segment could be deleted 
by another process. 


SegSize Size of a memory segment 
BX The memory segment handle. 

RETURN: 
AX Memory segment size in paragraphs. 

PANIC: 
PanicSeg3 BX was not a valid memory segment handle. 


Returns the size of an open memory segment. 


The size returned is the size of the memory segment in paragraphs. The handle must be one returned from 
the segCreate OF SegOpen Services. 


EPOC O/S SYSTEM SERVICES 


SegAdjustSize 


Adjust the size of a memory segment 


BX The memory segment handle. 

CX The new memory segment size in paragraphs. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

NoMemoryErr Not enough memory to satisfy the request. 
PANIC: 

PanicSegl Requested size was negative. 

PanicSeg3 BX was not a valid memory segment handle. 


Adjust the size of an open memory segment. 


The handle must be one returned from the segcreate Or SegOpen Services. CX must be positive (i.e. in the 
range 0000h to 7fffh) and represents the new size of the memory segment in paragraphs. Setting CX to 
zero will discard all the memory allocated to the memory segment but will not delete the segment itself. 


SegFind Find all segments 


BX The find handle. 

ES:DI Pointer to a wild card match string. 

DS:SI Pointer to the buffer to receive the name of the found segment. 
RETURN: Carry clear 

AX The find handle for the next find. 
RETURN: Carry set 

NotExistsErr No more segments found. 
PANIC: 

PanicSeg3 BX was not a valid find handle. 


Finds all the segments running which match the wild card string pointed to by DI. 


The first time this service is called, BX should be set to zero; the first segment will be found. After a find, 
this service returns the find handle in the AX register. The find handle must be supplied on the next call 
to this service to find the next segment running. 


No memory is used by this service and it can be abandoned at any time without taking any further action. 
The wild card string must always be supplied in DI and should be the same between calls to this service. 
The buffer pointed to by SI should be MaxNamersize+2 In size. 


SegCopyTo Copy to a memory segment 


BX The memory segment handle. 
cx The number of bytes to copy. 
DS:SI The source of the data, in the current process, to be copied. 
DX:DI The target offset in the memory segment. 
RETURN: None 
PANIC: 
PanicSeg3 BX was not a valid memory segment handle. 
PanicSeg4 DX:DI + CX exceeded the memory segment size. 


Copy data from the current process to an open memory segment. 


The handle must be one returned from the segcreate Or SegOpen Services. CX bytes are copied from 
DS:SI to the memory segment at offset DX:DI from the base of the memory segment. DX:DI is the offset 
in the memory segment for the target of the copy, as a 32 bit integer, with DI as the least significant word 
and DX as the most significant word. If DX:DI + CX is greater than the size of the memory segment, then 
the process will be panicked. 


While the copy is being effected no other process can access the memory segment. 


2 SEGMENTED MEMORY MANAGEMENT 


SegCopyFrom Copy from a memory segment 
BX The memory segment handle. 
cx The number of bytes to copy. 
DS:SI The target of the data, in the current process, to receive the copied 
data. 
DX:DI The source offset in the memory segment. 
RETURN: None 
PANIC: 
PanicSeg3 BX was not a valid memory segment handle. 
PanicSeg4 DX:DI + CX exceeded the memory segment size. 


Copy data to the current process from an open memory segment. 


The handle must be one returned from the segcreate Or SegOpen Services. CX bytes are copied from offset 
DX:DI in the memory segment to DS:SI in the current process. DX:DI is the offset in the memory 
segment, for the source of the copy, as a 32 bit integer, with DI as the least significant word and DX as the 
most significant word. If DX:DI + CX is greater than the size of the memory segment, then the process 
will be panicked. 


While the copy is being effected no other process can access the memory segment. 


SegRamDiskUsed Size of RAM disk 


None 
RETURN: 

AX Size of the RAM disk in paragraphs. 
PANIC: None 


Returns the size, in paragraphs, of the RAM disk (LOC::M:). 


On machines containing more than 512 kilobytes of RAM, the RAM disk will be created in an upper 
bank. In this case, unless the RAM disk overflows into the addressable RAM, SegRamDiskUsed will 
generally return zero. 


The value returned should be treated with some caution as the size of the RAM disk in a multi-tasking 
environment is a dynamic function of the requests of all the currently running processes. 


CHAPTER 3 


HEAP MEMORY MANAGEMENT 


Dynamics of heap memory 


When a process is created using the ProcCreate service, the process is allocated an initial heap size. It is 
also possible, if required, not to have a heap at all by specifying an initial heap size of zero. A process is 
guaranteed its initial heap on start up and from then on it will have to contend with all the other processes 
in the system for memory. 


Whenever the heap allocator runs out of memory, it will try and increase the size of the process’ data 
segment in order to satisfy the memory request. The data segment is grown in fixed sizes dependent on a 
parameter held for each individual process. This value is initialised on process creation with the value 
HeapGrowByDefault. This value can be altered at any time by calling the HeapSetGranularity service. 


Whenever the system runs out of segment memory it will try and compress the heap space of every 
running process by determining whether there is a free cell at the end of the heap. If there is, then the data 
segment will be shrunk, but only within the bounds of the initial heap size that the process was created 
with. Thus the initial heap size will be maintained throughout the life of the process. 


The maximum size of the heap is a function of the size of the stack, the size of the initialised and 
uninitialised data areas and the largest size that the data segment can be grown. The maximum size for a 
data segment is Offeh paragraphs. As an example consider a process that has 1K of stack, 4K of initialised 
data and 5K of uninitialised data, then the maximum possible size of the heap would be, OffeOh-0400h- 
1000h-1400h which is Ode70h bytes. 


HeapAllocateCell Allocate heap memory 
cx Size of the cell to be allocated in bytes. 
RETURN: = Carry clear 
AX Base of cell. 
RETURN: Carry set 
NoMemoryErr Not enough memory for the request. 
PANIC: 
PanicHeap2 Heap is not initialized. 


Allocates a cell in the process' heap memory. 


The cell will be at least the size requested in CX and can possibly be bigger. The cell will always start on 
an even memory address and will have an even length. This service can result in the process’ data segment 
growing in size. 


EPOC O/S SYSTEM SERVICES 


HeapReAllocateCell 


BX 
CX 

RETURN: Carry clear 
AX 

RETURN: Carry set 
NoMemoryErr 

PANIC: 
PanicHeap2 
PanicHeap4 


Re-allocate heap memory 


The base of the cell to be re-allocated or zero. 


The new size of the re-allocated cell in bytes. 
Base of the re-allocated cell. 
Not enough memory for the request. 


Heap is not initialised. 


The base of the cell is not in the heap memory area. 


Re-allocates a cell in the process’ heap memory. 


A previously allocated cell can be changed in size by calling this service. The cell can be made larger or 
smaller. If the value in the BX register is zero then this service performs in exactly the same way as the 


HeapAllocateCell service. 


If a cell is being extended then the service will attempt to do so by using any free memory existing 
immediately after the cell. If there is no free memory then the cell will be moved elsewhere and extended. 
Thus the value returned in AX will often not be the same as that passed in the BX register. i.e. do not rely 
on old copies of the cell base after a call to the HeapReAllocateCell service. The cell will be at least the 
size requested in CX and can possibly be bigger. The cell will always start on an even memory address 


and will have an even length. 


Any changes to the cell always occur at the end of the cell. Thus if the cell is extended then it will be 
extended at the end and the data currently in the cell will be untouched. If the cell is shrunk then the 
shrink will be at the end of the cell and the data at the end of the cell will be lost. This service can result 
in the process' data segment growing in size. 


HeapAdjustCellSize 


BX 
cx 
Dx 

RETURN: Carry clear 
AX 

RETURN: Carry set 
NoMemoryErr 

PANIC: 
PanicHeap2 
PanicHeap3 
PanicHeap4 


Adjust the size of heap memory 


Base of cell to be adjusted. 
Adjustment to the size of the cell in bytes. 


Offset in the cell to make the adjustment. 
Base of cell after adjusting. 

Not enough memory to satisfy the request. 
Heap is not initialised. 


Offset of adjust is greater than cell size. 


The base of the cell is not in the heap memory area. 


Adjust the size of the cell at BX, at an offset DX in the cell, by CX bytes. 


The cell will be shrunk if CX is negative and grown if CX is positive. As this service can call the 
HeapReAllocateCell service, the cell may be moved if it is being extended. Thus the value returned in 
AX need not be the same as that passed in BX. Unlike the HeapReAllocateCell service BX may not be 
zero, i.e. the cell must already be allocated. This service can result in the process' data segment growing in 


size. 


3 HEAP MEMORY MANAGEMENT 


HeapFreeCell Free heap memory 
BX Base of cell. 

RETURN: None 

PANIC: 
PanicHeap2 Heap is not allocated. 
PanicHeap4 The base of the cell is not in the heap memory area. 


Free the memory cell whose base is in the BX register. The value passed in BX must be as returned from 
HeapAllocateCell, HeapReAllocateCell Of HeapAdjustCellSize. 


HeapCellSize Size of a heap cell 
BX Pointer to the base of cell. 
RETURN: 
AX Cell size in bytes. 
PANIC: 
PanicHeap2 Heap is not allocated. 
PanicHeap4 The base of the cell is not in the heap memory area. 


Returns the size of a cell allocated in heap memory. This size is guaranteed to be even. 


HeapSetGranularity Set the heap granularity 
BX The new granularity in paragraphs. 

RETURN: None 

PANIC: 
PanicHeap2 Heap is not allocated. 
PanicHeap3 Attempt to set the granularity bigger than MaxHeapGrowBy. 


Set the heap granularity parameter to the value in BX. 


The maximum value for the heap granularity is MaxHeapGrowBy. Whenever the heap allocator runs out of 
memory, it will try and increase the size of the process' data segment in order to satisfy the memory 
request. The data segment is grown in fixed sizes dependent on a parameter held for each individual 
process. This value is initialised on process creation with the value HeapGrowByDefault. 


HeapFreeMemory Size of available heap memory 


None 
RETURN: 
AX Number of bytes potentially available in the heap. 
BX Address of the base of the heap memory. 
PANIC: 
PanicHeap2 Heap is not allocated. 
Returns the size of potentially available heap memory and the address of the base of the heap memory. 


The size returned in AX consists of the amount of free memory in the heap that is currently available plus 
the amount by which the heap could be extended. 


The value returned should be treated with some caution as the amount of available memory in a multi- 
tasking environment is a dynamic function of the memory requests of all the currently running processes. 


CHAPTER 4 


SEMAPHORE MANAGEMENT 


SemCreate Create a semaphore 
BX Initial semaphore count. 
RETURN: = Carry clear 
AX Semaphore handle. 
RETURN: Carry set 
NoSemaphoreErr No semaphores are available. 
PANIC: 
PanicSem3 Requested initial count was negative. 


Creates a semaphore, owned by the calling process, with an initial count as specified in BX. 


A process should delete any owned semaphores before exiting but if it should exit abnormally or be 
panicked then the Supervisor will automatically delete it on behalf of the process. 


SemDelete Delete a semaphore 
BX The semaphore handle. 

RETURN: None 

PANIC: 
PanicSem1 Invalid semaphore handle. 
PanicSem2 Semaphore not allocated. 


Deletes a semaphore identified by the handle passed in BX. The handle in BX should be the one returned 
from the segcreate service. Any processes waiting on the semaphore are automatically signalled. 


SemWait Wait on a semaphore 
BX The semaphore handle. 

RETURN: None 

PANIC: 
PanicSem1 Invalid semaphore handle. 
PanicSem2 Semaphore not allocated. 


Waits for a semaphore to be signalled. 


If the semaphore has a count greater than 0 then semwait will return immediately. If the semaphore has a 
count of 0 or less then the process will wait on the semaphore queue until the semaphore is signalled. 
More than one process can be waiting on a semaphore at a time, in which case the process that is released 
from the queue is on a first wait, first release basis. 


If the semaphore that is being waited on has been deleted because the owning process has explicitly 
deleted it, exited or been panicked, then the waiting processes will be automatically released. There is no 
way of determining that this has happened other than co-operation between the processes sharing the 
semaphore. 


EPOC O/S SYSTEM SERVICES 


SemSignalOnce Signal once 
BX The semaphore handle. 

RETURN: None 

PANIC: 
PanicSem1 Invalid semaphore handle. 
PanicSem2 Semaphore not allocated. 


Signals a semaphore once. 


If the signalled semaphore has a count less than zero then the first process waiting on the semaphore will 
be released and a re-schedule will take place. If the count is zero or positive then the count will just be 
incremented. 


SemSignalMany Signal more than once 
BX The semaphore handle. 
cx The number of signals. 
RETURN: None 
PANIC: 
PanicSem1 Invalid semaphore handle. 
PanicSem2 Semaphore not allocated. 
PanicSem4 CX not greater than or equal to 1. 


Signals a semaphore by the count in CX, which should never be negative. 


If the signalled semaphore has a count less than zero then up to CX waiting processes will be released and 
a re-schedule will take place. If the count is zero or positive then the count will just be incremented by the 
value in CX. 


SemSignalOnceNoReSched Signal once without re-schedule 
BX The semaphore handle. 

RETURN: None 

PANIC: 
PanicSem1 Invalid semaphore handle. 
PanicSem2 Semaphore not allocated. 


Signals a semaphore once with no re-schedule. 


If the signalled semaphore has a count less than zero then the first waiting process will be released. 
However, unlike semsignalonce, a re-schedule will not take place. This guarantees that the call to this 
service will return to the caller immediately. If the count is zero or positive then the count will just be 
incremented. 


If this service is used instead of semsignalOnce Of SemSignalMany then the next re-schedule will only 
occur on the expiration of the next time slice. This may unnecessarily delay the signalled process. In order 
to overcome this, a re-schedule can always be forced by calling the TimsleepForTicks service with a value 
of 0. 


CHAPTER 5 


MESSAGE MANAGEMENT 


Inter process communication 


The messaging subsystem is a very important part of the operating system as it allows the high speed 
passing of information between processes. 


Any process can send a message to another process if the target process is prepared to receive messages. 
However, a process can only receive messages if it has previously initialised the message system by calling 
the MessInit service. 


A message consists of the header as described in the structure MessEnt followed by a buffer whose length 
is specified by the process receiving the message, when it calls the MessInit service. The sending process 
has no control over how much data is sent to the receiving process. 


When a process sends a message it just specifies a message type, which is a 16 bit integer, and the address 
of a buffer. The receiving process will get the message and the following information 


e The message type as specified by the sender. 
e The process id of the sender. 
e The first X bytes of data from the buffer where X is the number specified to the MessInit service. 


The actual information content of message is defined by the receiver of the message and should be limited 
to as small a number as possible. For example the file server and the supervisor are both communicated 
with by messages where the number of bytes of information is 8. 


It will often be necessary for processes to send more than the amount of information allowed for by the 
receiving process in the message buffer. In this case all that is necessary is to send the address of the 
buffer and the length of the data in the message. 


The receiving process can then call the procCopyFromById and ProcCopyToById services to either copy 
data to or from the sending process. 


eee nee ee eee ee ey | 
Order of message reception 


When a process initialises the message system, a queue is created to hold received messages. The number 
of entries which can be held in the queue is specified to the MessInit service. 


Messages arriving are queued in arrival order and are normally removed in arrival order. However 
messages sent by a process whose priority is greater than 0x80 will jump to the beginning of the queue. 


When a process sends a message to another process, two outcomes are possible: 


e There will be room in the target process' queue, in which case the message will be delivered and 
the process will not wait. 


e  =There will be no room in the target process’ queue, in which case the process will wait until there 
is room in the queue. As soon as there is room and the process gains a time slice, the message 
will be delivered as previously. 


5-1 


EPOC O/S SYSTEM SERVICES 


The message system and the I/O system 


The message system has been designed to follow the I/O system very closely; in particular both systems 
share the following features: 


e Asynchronous and Synchronous capability. 
¢ Completion status words containing PendingErr while the request is still outstanding. 
e Synchronisation through the tosignal, IoWaitForSignal, IoWaitForStatus Services. 


This makes it possible to mix asynchronous messaging with asynchronous I/O. 


Messlnit Initialise the message system 
BL The number of messages allowed in the message queue. 
BH The length of messages excluding the MessEnt structure. 
RETURN: Carry clear 
Success. 
RETURN: Carry set 
NoSemaphoreErr No free semaphores left. 
NoMemoryErr Not enough memory to allocate the message queue. 
PANIC: 
PanicMess1 Messages are already initialized. 
PanicHeap3 Invalid number of messages specified. 


Initialises the message system. 


BL messages are allowed for in the message queue. BH specifies the size of a message but excludes the 
size of the MessEnt structure which is at the front of all messages. 


The message queue is allocated in the process' heap memory and, as such, it is recommended that 
processes which call this service should do so as early in their initialisation as possible. All messages are 
the same size, and the size of the message queue can be calculated as follows: 


BL * (BH + size of MessEnt) bytes. 


In general, programs which are servers for all the other processes should allocate enough message entries 
to ensure that there is room in the queue for every process to deliver a message. The constant 
MaxProcesses contains the total number of processes which can be supported by the system. In practice 
this can be reduced by four - for the NULL, Supervisor, File Server and Window Server processes. 


MessReceiveAsynchronous Asynchronous message reception 


DS:BX Pointer to a word to receive the address of the message received. 
DS:DI Pointer to the status word. 
RETURN: None 
PANIC: 
PanicMess2 Messages are not initialised. 
PanicloPending Already waiting for a message. 


Queues a request to receive a message and returns immediately. 


If there are no messages waiting in the queue then the status word will contain pendingErr and the 
process can wait for completion by calling the 1oWaitForSignal Of IoWaitForStatus services. If there is 
a message waiting in the queue then the status word will contain the value nozrr, i.e. zero. The process 
must still call either the towaitForSignal Or IoWaitForStatus services to balance the signal which is 
sent on receiving a message. 


5 MESSAGE MANAGEMENT 


When the message has been received then the word pointed to by BX will contain the address of the 
message. After the process has finished with the data in the message, the message should be returned to 
the queue using the MessFree service. If messages are not freed then eventually the message queue will be 
empty and any process sending a message will wait indefinitely. 


MessReceiveWithWait Synchronous message reception 
DS:BX Pointer to a word to receive the address of the message received. 
RETURN: None 
PANIC: 
PanicMess2 Messages are not initialised. 
PanicloPending Already waiting for a message. 


Waits for a message to be received. 


When the message has been received then the word pointed to by DS:BX will contain the address of the 
message. After the process has finished with the data in the message, then the message should be returned 
to the queue using the MessFree service. If messages are not freed then eventually the message queue will 
be empty and any process sending a message will wait indefinitely. 


MessReceiveCancel Cancel queued message receive 
None 

RETURN: None 

PANIC: 
PanicMess2 Messages are not initialised. 


If a request to receive a message has been queued with the MessReceiveAsynchronous Service then the 
request may be cancelled with the MessReceiveCancel service. 


It is not considered an error to call this service if no request is outstanding. After this service has been 
called, a signal will be delivered and the status word will be changed to cancelzrr. Note that this service 
can not be called to cancel a request pending from the MessSendReceiveAsynchronous Service. 


MessSend Send messages 
BX The id of the process to receive the message. 
CX The type of message. 
SS:SI Pointer to the message buffer. 


RETURN: Carry clear 
Success. 
RETURN: Carry set 
NoReceiverErr The target process does not exist. 
PANIC: None 
Sends a message to the process whose id is specified in the BX register. 
If the target process either does not exist or has not initialised messages, the service will return the 
NoReceiverErr. The message, when it arrives, will have the field Messtype in the MessEnt structure set to 


the value passed in the CX register. The rest of the message will be copied from the buffer pointed to by 
SS:SI. 


There is no need to specify the length of the data to be copied as it is not a function of the sending process 
but a function of the receiving process. If the target process' message queue is full, the sending process 
will be suspended until space becomes available in the queue. 


EPOC O/S SYSTEM SERVICES 


MessSendReceiveAsynchronous Send and get a reply async 
BX The process id to receive the message. 
cx The type of message. 
DI Pointer to the status word. 
SS:SI Pointer to the message data. 


RETURN: Carry clear 
Success. 
RETURN: Carry set 
NoReceiverErr The target process does not exist. 
PANIC: None 
Sends a message to a process and returns without waiting for the reply from that process. 
The target process is as specified by the process id in BX, the message type is in CX and the message data 


is pointed to by SS:SI. These parameters have the same meaning as for MessSend. The pointer to the 
status word is specified by DI. 


When the target process eventually frees the message then the reply will be returned in the status word 
pointed to by DI and a signal will be sent to the sending process. 


MessSendReceiveWithWait Send and wait for a reply 
BX The process id to receive the message. 
Cx The type of message. 
SS:SI Pointer to the message data. 
RETURN: Carry clear 
AX The received data. 
RETURN: Carry set 
NoReceiverErr The target process does not exist. 
Returned error Depends on the value returned by the target. 


PANIC: None 
Sends a message to a process and then waits for a reply from that process. 
The target process is as specified by the process id in BX, the message type is in CX and the message data 


is pointed to by SS:SI. These parameters have the same meaning as for Messsend. The target process 
returns the reply when it frees the message it received with the MessFree service. 


MessFree Freea message 
DS:BX Pointer to message to be freed. 
Cx The value to be returned to the sender of the message. 

RETURN: None 

PANIC: 
PanicMess2 Messages are not initialised. 


Returns a received message to the message queue. 


If messages are not returned to the message queue then in due course there will be no messages left in the 
queue and all sending processes will be suspended and only the receiver will be left running (wondering 
where everyone else has gone). 


If a message was sent with just a MessSend then the return value in CX is ignored. 


If a message was sent with MessSendReceiveWithWait Of MessSendReceiveAsynchronous then the value 
in CX is the returned reply. 


5 MESSAGE MANAGEMENT 


MessSignal Request a signal from the Supervisor 
BX The process id which will trigger the signal when it terminates. 
CX The message type to be sent when the process terminates. 


RETURN: Carry clear 


Success 
RETURN: Carry set 
NotExistsErr The requested process does not exist. 
PANIC: 
PanicMess2 Messages are not initialised. 


Notifies the supervisor to send a message of the type specified in CX to the process calling this service 
when the process specified in BX exits or is panicked. 


This service is very similar to loRequestReset in that it is a mechanism which allows processes and 
servers, in particular, to perform valuable housekeeping when a process connected to a server terminates. 


For example, when a process connects to the file server with the Filconnect service, the file server calls 
this service to register an interest in the process making the connection. When the process terminates, the 
file server will receive a message from the supervisor that the process has terminated and the server can 
then free all the resources associated with that process. 


When the process specified in BX terminates, a message will be sent from the supervisor with the type 
requested in CX. The first word in the message buffer is the id of the terminating process and the second 
word contains the exit code. The exit code is split into two bytes; the least significant byte has the actual 
reason for the termination and the most significant byte has the type of exit. This can be one of: 


@ KillExit - The process was killed or terminated; by convention, if the 
least significant byte (i.e. the reason for the termination) was 0 
then it was a non-error exit. 


@ PanicExit - The process was panicked. 
@ TaskPanicExit - A task in the process was panicked which caused the process 
itself to be panicked. 


Having registered an interest in a process with the supervisor, this interest can be cancelled by calling the 
MessSignalCancel service. When the process terminates, a signal will not be sent by the supervisor. 


The process must have messages initialised in order to request this service. 


MessSignalCancel Cancel requested signal from Supervisor 


BX The process id which will trigger the signal, when it terminates. 
RETURN: Carry clear 


Success. 
RETURN: = Carry set 
NotExistsErr The process has no signal request logged with the supervisor. 
PANIC: 
PanicMess2 Messages are not initialised. 


Cancels a previously requested signal from the supervisor as set up by an earlier call to Messsignal. 
BX contains the process id is as passed to an earlier call to Messsignal. 
The process must have messages initialised in order to request this service. 


This service is unsuitable for applications that have requested more than one signal for termination of the 
same process. In this situation, the application should use MesssignalCance1x; this allows the message 
type to be identified. 


EPOC O/S SYSTEM SERVICES 


?MessSignalCancelX Cancel signal from Supervisor by type 
BX The process id which will trigger the signal when it terminates. 
CX The message type to be sent when the process terminates. 


RETURN: Carry clear 


Success. 
RETURN: = Carry set 
NotExistsErr The process has no signal request logged with the supervisor. 
PANIC: 
PanicMess2 Messages are not initialised. 


Cancels a previously requested signal from the supervisor. 


The parameters to this function are exactly same as those to the MessSignal service which set up the 
signal in the first place. 


The process must have messages initialised in order to request this service. 


This service must be used in preference to MessSignalCancel in cases where two or more MessSignal 
requests are made with the same value of BX. 


CHAPTER 6 
DYNAMIC LIBRARY, CATEGORY AND OBJECT 


MANAGEMENT 


Library names 


All dynamic libraries have two names by which they may be referenced. 
e =©File name. 
e = Internal name. 


The file name of a dynamic library is just used to load the library into memory so that it can be used by 
other processes. The default extension for dynamic libraries is DYL. The file name should be used to load 
the library using the LibLoad Or LibLoadFile services. 


Once loaded, a dynamic library publishes a name by which the library is known to the system. This name 
just consists of the name and extension portion of the file name. 


An image can also be a dynamic library as well as an image in which case if the image name is 
NNNN.IMG or NNNN.APP the internal name published will be the name of the code segment, i.e. 


NNNN.$SC. 


LibLoad 


ES: BX 


CL 


RETURN: = Carry clear 


Load a dynamic library 


Pointer to the dynamic library file name. 
Zero - Don't link the library automatically. 


Non Zero - Link the library after loading. 


AX The dynamic library handle. 
RETURN: Carry set 
NameErr Invalid file name. 
NotExistsErr Dynamic library file does not exist. 
AlreadyOpenErr Dynamic library already loaded. 
ImageErr File is not a valid dynamic library file. 
PANIC: 
PanicObj6 All external references in the library could not be resolved. 
PanicFs1 Process not connected to the File Server. 


EPOC O/S SYSTEM SERVICES 


Loads a dynamic library into memory for access by the other Lib services. 


ES:BX points to a zero terminated file name which can be a full path name. If the dynamic library is 
already in memory then it will be shared and the library will not be re-loaded. This service can also invoke 
the LibLink service, depending on the value in CL. If CL is non-zero then the library will be linked after 
loading. Clearly if the library is already linked then this will be skipped. 


As long as the process keeps the dynamic library open, it will stay in memory. It is desirable that a process 
should unload the library, using the LibunLoad service as soon as it has finished using it. This allows 
memory to be freed for use by other processes. 


If the process should panic or be killed before it can close the library, the supervisor will automatically 
perform the unload. Note that the process must be connected to the file server before this service can be 
called. 


LibUnLoad Unload a dynamic library 


BX Handle for the dynamic library. 
RETURN: Carry clear 

Success. 
RETURN: Carry set 

NotOpenErr Process does not have the library opened. 


PANIC: None 
Unloads a dynamic library from memory. 
A loaded dynamic library can be shared by many processes; each time a process loads it, the library access 


count is incremented. Unloading the library decreases the access count. If the access count is 0 after 
unloading the dynamic library, it will be discarded from memory. 


As dynamic libraries are in memory, it is important that programs unload a library as soon as they have 
finished using it. If a program is terminated for any reason, then the supervisor will automatically call this 
service for any library still loaded. 


LibLink Link a dynamic library 


BX Handle to the dynamic library. 
RETURN: None 
PANIC: 
PanicObj6 All external references in the library could not be resolved. 


Links a dynamic library which is already in memory. 


If the library has already been linked because another process has already loaded and linked it then this 
service just returns. 


All external categories which are required to satisfy external references in the library to be linked must 
already be in memory or on the ROM disk before this service is called, otherwise Panicob 6 will be 
generated. 


Programs, i.e. IMG files which contain a category must request this service to link themselves before any 
classes can be accessed. In order to specify the SELF category, the handle BX must be 0. Normally the 
handle will have been returned by LibLoad Of LibFind. 


LibFind Get a dynamic library handle 


ES:BX Pointer to the dynamic library internal name. 
RETURN: Carry clear 

AX The dynamic library handle. 
RETURN: Carry set 

NotExistsErr The dynamic library is not loaded into memory. 


PANIC: None 


6 DYNAMIC LIBRARY, CATEGORY AND OBJECT MANAGEMENT 


Given the internal name of a dynamic library, this service will return a handle to that library. The library 
must exist on the ROM disk or have been loaded by the program. 


Having found a handle to a library, it can be used to create objects using the classes contained in that 
library by invoking the LibcreateByHandle Service. 


LibHandle Get a DYL handle by number 


BX The number of the required external category. 
RETURN: 
AX The category handle. 
PANIC: 
PanicObj2 Number does not specify a valid external category. 
PanicObj5 Attempt to get a handle before the SELF category has been linked. 


When a category is generated, it may contain references to external categories. After calling the LibLink 
service, these external references are resolved. In order to get a handle to these external categories, this 
service may be called by using the number provided by the category compiler. This number will be defined 
as CAT_... If this service is passed a value of 0 in BX, it will return 0 as the handle for the self category 
is also 0. 


This service is used by the Libcreate service. 


LibCreate Create an object by category number 
BX The number of the category. 
CX The number of the class within the category. 
RETURN: Carry clear 
AX The object handle. 
RETURN: Carry set 
NoMemoryErr The object could not be created. 
PANIC: 
PanicObj2 Number does not specify a valid external category. 
PanicOb33 Number does not specify a valid class. 
PanicObj5 Attempt to get a handle before the SELF category has been linked. 


Two components are always required to specify a class from which an object is to be created: 
e The category handle. 
e The class number. 


This service converts the category number passed in BX to a handle by calling the LibHandle service and 
then calling the LibcreateByHandle Service. 


The category number can be 0, meaning the SELF category or the number of an external category as 
created by the category compiler. 


The class number in CX is as created by the category compiler. The handle to the object created is 
returned in AX, if carry is clear. The only error which can occur is an out of memory condition. The 
object's data will be initialised to zero by this service. 


LibCreateByHandle Create an object by category handle 
BX The handle of the category. 
Cx The number of the class within the category. 
RETURN: Carry clear 
AX The object handle. 
RETURN: Carry set 
NoMemoryErr The object could not be created. 


EPOC O/S SYSTEM SERVICES 


PANIC: 
PanicObj2 Number does not specify a valid external category. 
PanicOb33 Number does not specify a valid class. 
PanicObj5 Attempt to get a handle before the SELF category has been linked. 


The category handle can be 0 to mean the SELF category, otherwise it must be a handle returned by 
LibFind, LibLoad Of LibHandle. 


The class number in CX is as created by the category compiler. The handle to the object created is 
returned in AX, if carry is clear. The only error which can occur is an out of memory condition. The 
object's data will be initialised to zero by this service. 


LibDestroy Destroy an object 


BX The handle of the object to be destroyed. 
RETURN: None 
PANIC: None 
This service will de-allocate all the memory associated with an object including any compound objects. 


This service is normally called by the root class in its DESTROY method. As this is the ultimate super 
class, all objects are inherently able to destroy themselves. 


e LibSend Send a message 
BX The handle of the object to receive the message. 
CL The message number to be sent. 
DX Argument | 
SI Argument 2 
DI Argument 3 
RETURN: 
AX Whatever the method returns. 
PANIC: 
PanicOb3j0 No method prepared to handle the message number in CX. 


This service will send a message to an object. 


Any arguments to the method eventually invoked should be allocated to the registers DX,SI and DI in that 
order. The search for a method starts in the class which was used to create the object. 


e LibSendSuper Send a superclass message 
BX The handle of the object to receive the message. 
CL The message number to be sent. 
DX Argument | 
SI Argument 2 
DI Argument 3 
RETURN: 
AX Whatever the method returns. 
PANIC: 
PanicOb3j0 No method prepared to handle the message number in CX. 


This service will send a message to an object. Unlike Libsena, however, the search for a method starts in 
the object's immediate superclass. This is the way in which inheritance works. 


6 DYNAMIC LIBRARY, CATEGORY AND OBJECT MANAGEMENT 


e LibSendExact Send a direct message 
DS: [DatEClassHandle] The category handle. 
DS: [DatEClassPtr] The class number. 
BX The handle of the object to receive the message. 
CL The message number to be sent. 
DX Argument | 
SI Argument 2 
DI Argument 3 
RETURN: 
AX Whatever the object returns. 
PANIC: 
PanicOb3j0 No method prepared to handle the message number in CX. 


This service will send a message to an object. Unlike Libsena, however, the search for the method starts 
at the class specified in DS:[DatEClassHandle],DS:[DatEClassPtr]. 


e LibEnterSend Send message under protection of Enter 
BX The handle of the object to receive the message. 
CL The message number to be sent. 
DX Argument | 
SI Argument 2 
DI Argument 3 
RETURN: 
AX Whatever the method returns or is passed to LibLeave. 
PANIC: 
PanicOb3j0 No method selected by CX. 


This service will send a message to an object. 
The first two arguments are mandatory; the other arguments depend on the method being selected. 


The search for a method starts in the class which was used to create the object. Unlike Libsend the 
method called is entered as if it had been called with LibEnter. Thus any LibLeave calls from the method 
itself or any of the routines which it may call can be made to return to the caller of this service. 


LibOpen Open a multi library file 


ES:BX Pointer to the file name. 
RETURN: Carry clear 

AX The open multi library file handle. 
RETURN: Carry Set 

ImageErr Not a multi library file. 

Error Any error that Filopen can give. 
PANIC: 

PanicFs1 Process not connected to the File Server. 


This service opens a file which contains multiple libraries. 


Most commonly this is an image file to which the multiple libraries have been added using the OsMake 
tool. 


The returned handle in AX can be used with LibLoadrile to load libraries. The handle is a normal file 
handle as if the file had been opened with rilopen and, as such, when access to the file is no longer 
required it can be closed with Fiiclose. 


EPOC O/S SYSTEM SERVICES 


LibLoadFile 


BX 
CH 


CL 


RETURN: Carry clear 
Success. 
RETURN: Carry set 
AlreadyOpenErr 
ImageErr 
PANIC: 
PanicObj6 


PanicFs1l 


Load a multiple dynamic library 


Multiple library file handle. 
The index of the library to be loaded. 
Zero - Don't link the library automatically. 


Non Zero - Link the library after loading. 


Dynamic library already loaded. 
File is not a valid dynamic library file. 


All external references in the library could not be resolved. 


Process not connected to the File Server. 


Loads a dynamic library from an already opened multiple library file into memory for access by the other 


library services. 


The handle in BX must have been provided by the Libopen service. CH selects the library to be loaded 
from the file in the order that libraries were added to the image originally. Thus 0 will load the first 
library from the file, 1 the second and so on. 


If the dynamic library is already in memory then it will be shared and the library will not be re-loaded. 
This service can also invoke the LibLink service, depending on the value in CL. If CL is non zero then the 
library will be linked after loading. Clearly if the library is already linked then this will be skipped. 


As long as the process keeps the dynamic library open, it will stay in memory. It is desirable that a process 
should unload the library, using LibUnLoad, as soon as it has finished with it so that the memory can be 
used by other processes. If the process should panic or be killed before it can close the library, the 
supervisor will automatically perform the unload. 


Note that the process must be connected to the file server before this service can be called. 


LibReClass 


BX 

CX 

DI 
RETURN: None 
PANIC: 

PanicObj2 

PanicObj3 

PanicObj5 


Reclass an object by number 


The number of the category. 
The number of the class within the category. 


Pointer to the object to be reclassed. 


Number does not specify a valid external category. 
Number does not specify a valid class. 


Attempt to get a handle before the SELF category has been linked. 


There are always two components to specifying a class in order to reclass an object. 


e The category handle. 


e  §=The class number. 


This service converts the category number passed in BX to a handle by calling the LibHandle service and 
then calling the LibReClassByHandle service. The category number can be 0 meaning the SELF category 
or the number of an external category as created by the category compiler. The class number in CX is as 


created by the category compiler. 


6 DYNAMIC LIBRARY, CATEGORY AND OBJECT MANAGEMENT 


LibReClassByHandle Reclass an object by handle 


BX The handle of the category. 
Cx The number of the class within the category. 
DI Pointer to the object to be reclassed. 
RETURN: None 
PANIC: 
PanicObj2 Handle does not specify a valid external category. 
PanicOb33 Number does not specify a valid class. 


This service changes the class to which an object belongs to that specified by BX and CX. 


It is up to the user to ensure that the new class that the object will belong to will behave appropriately. BX 
must be the handle on an already loaded category. The class number in CX is as created by the category 
compiler. 


LibCopy Copy data from a category 


BX The category number. 

CX Number of bytes to copy. 

DI Pointer to a buffer to receive the data. 

SI Offset of the source in the category segment. 
RETURN: None 
PANIC: 

PanicObj2 Number does not specify a valid external category. 


This service will copy data from a category segment into the data segment of the current process. The 
category is specified by the number in BX, which will be converted to a handle with LibHandie. The offset 
in the category is specified by the value in SI. 


e LibEnter Enter a control region 
AX The routine to call. 
BX Argument 1. 
CX Argument 2. 
DX Argument 3. 
SI Argument 4. 
DI Argument 5. 
RETURN: 
AX Whatever the routine called or is passed to the LibLeave service. 


PANIC: None 


This service will call a routine in a transparent fashion, while marking this call as entering a control 
region. A subsequent call to the LibLeave service will immediately exit from this service. Control regions 
can be nested. 


e LibLeave Leave a control region 
AX The value to return. 

RETURN: None 

PANIC: 
PanicEnterl No corresponding call to LibEnter. 


This service can be called to exit from a control region. 


The value in AX will be returned in AX to the original caller of the LibEnter service which set up the 
control region. 


All images must have a call to LibLeave at offset OxOC in the code segment of the image. 


EPOC O/S SYSTEM SERVICES 


e LibExitSend Return from a method 


AX The value to return. 
RETURN: None 
PANIC: None 
This service can be called to exit from a method. 
Normally this routine is not called directly and is used by the C libraries to effect the exit from p_send() 


etc. All images must have a call to the LibSendExit service at offset OxOC in the code segment of the 
image. 


CHAPTER 7 


DEVICE MANAGEMENT 


Device names 


Device names are zero terminated strings made up in one of the following ways: 
e 3characters followed by a colon 
e 3characters, period and 3 characters followed by a colon 


Examples of valid names are as follows: 


e §6TTY: 
e = TTY.ASS: 
e = FIL: 


| 
Device drivers 


There are two kinds of device drivers supported by Epoc/Os. 
e LDD - logical device driver. 
e PDD - physical device driver. 


LDDs provide a consistent interface through the I/O services to application programs. Thus there is only 
one RS232 LDD available which will handle all the RS232 devices in the system. 


PDDs provide the interface by which LDDs access the hardware. Thus there can be a Psion custom RS232 
PDD and a standard 16450 UART PDD in the system controlling very different hardware devices. 
However because all access to the hardware is through the LDD and then to the PDD both devices will 
behave in exactly the same way as far as application programs are concerned. 


LDDs are opened using the Ioopen service, while PDDs are opened using the Devopenppp service. An 
application should never try and access the hardware by opening a PDD directly. 


LDDs all have three character names, i.e. TTY, PAR, while PDDs have a seven character name, 
i.e. TTY.ASS, TTY.UAR, where the first part of the name represents the owning LDD. 


DevOpenPDD Open a physical device driver 


ES:BX Pointer to the PDD name. 
RETURN: = Carry clear 
AX Device handle 


EPOC O/S SYSTEM SERVICES 


RETURN: Carry set 


NotExistsErr The specified PDD does not exist. 

Error Error returned by the device driver. 
PANIC: 

PanicLibl The named device driver was not a PDD. 


Open the physical device driver identified by the name pointed to by ES:BX. 


The device must already be installed either as a built in device driver or as a dynamic device driver. The 
DevLoadppp service should be used to load a PDD device driver into memory if it is not already loaded. 
The open service returns a device handle which can be used by the pevGetPpDAddress Service to get the 
far address of the PDD strategy entry point. 


The functions that can be performed by a PDD are documented on a per device driver basis. 


DevGetPDDAddress Get the PDD entry point 


BX The PDD device handle. 
RETURN: 
BX: AX The PDD entry point 
PANIC: 
PanicDevl The device handle is not for a PDD or is invalid. 


This service returns the address of the PDD's entry point. 


The PDD's device handle is passed in BX. The entry point is returned in the BX:AX registers, where BX 
is the segment address and AX is the offset. This allows a far call to be made to the PDD. Opening the 
PDD will return the device handle for the PDD. After a resume, the entry point of the PDD should be 
re-loaded as the code may have moved. 


Devinstall Install a device driver 
BX LHDSeg. 
CX LHDPtr. 
Dx LDDSignature - LDD device type. 


PDDSignature - PDD device type. 
RETURN: Carry clear 
Success. 
RETURN: = Carry set 
DeviceErr Not a valid device driver. 
PANIC: None 


This function is reserved for use by the operating system and should never be used by applications. It is 
called automatically by the pevLoadipp and DevLoaappp services. After an LDD has been loaded its install 
vector will be executed. This is not the case for a PDD. 


DevHold Hold all device drivers 


CL DevHoldNormal - Device memory is being moved. 
DevHoldPowerDown - The machine is switching off. 


DevHoldPowerFail - The machine is switching off after a power fail 
condition has been detected. 


RETURN: None 
PANIC: None 


This function will call all the LDDs in the system in turn to suspend all interrupt driven devices which are 
currently active. They can subsequently be re-activated by calling the DevResume Service. It is strongly 
recommended that this service is not called and that its use is restricted to the operating system. It is 
called by the pevLoadLpp and DevLoadpPpp services. 


7 DEVICE MANAGEMENT 


DevResume Resume all device drivers 


None 
RETURN: None 
PANIC: None 


This function will call all the LDDs in the system in turn to resume all interrupt driven devices which 
were previously de-activated by DevuHo1d. It is strongly recommended that this service is not called and 
that its use is restricted to the operating system. It is called by the DevLoadLpp and DevLoadPDD services. 


DevLoadLDD Load a logical device driver 


ES:BX Pointer to the name of a file containing the logical device driver. 
RETURN: Carry clear 


Success 
RETURN: = Carry set 
NotExistsErr Logical device driver file does not exist. 
ImageErr Logical device driver file does not have the correct format for a 
LDD. 
PANIC: 
PanicFs1 The process is not connected to the file server. 


Load the logical device driver from the file identified by the name pointed to by ES:BX. 


If no extension is given for the file name then a file extension of .LDD will be assumed. If a full path 
name is not given then the current directory will be searched for the LDD file. After the LDD is loaded it 
may then be accessed using the I/O services in the normal way. 


DevLoadPDD Load a physical device driver 


ES:BX Pointer to the name of a file containing the physical device driver. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

NotExistsErr Physical device driver file does not exist. 

ImageErr Physical device driver file does not have the correct format for a 

PDD. 

PANIC: 

PanicFs1 The process is not connected to the file server. 


Load the physical device driver from the file identified by the name pointed to by ES:BX. 


If no extension is given for the file name then a file extension of .PDD will be assumed. If a full path 
name is not given then the current directory will be searched for the PDD file. After the PDD is loaded it 
may then be accessed using the I/O services in the normal way. 


DevDelete Delete a device driver 
ES:BX Pointer to the name of the device driver to be deleted. 
Dx LDDSignature - LDD device type. 


PDDSignature - PDD device type. 
RETURN: Carry clear 


Success 

RETURN: = Carry set 
NotExistsErr The device driver is not currently loaded. 
Not SupportedErr The device driver is a ROM device driver and cannot be deleted. 
InUseErr The device driver is currently open and cannot be deleted. 
Error number Error returned by the device driver. 


EPOC O/S SYSTEM SERVICES 


PANIC: 
PanicFs1 The process is not connected to the file server. 
Delete the requested device driver of the name pointed to by ES:BX. 
The name here should be the same name which would be passed to the open services. Only device drivers 
in RAM can be deleted by this service. DX specifies whether an LDD or a PDD is to be deleted. In both 


cases the remove vector will be executed before the device is deleted from memory. Calling this service 
will result in the DevHold and DevResume services being called. 


DevRemove Remove a device driver 
ES:BX Pointer to the name of the device driver to be removed. 
Dx LDDSignature - LDD device type. 


PDDSignature - PDD device type. 
RETURN: = Carry clear 


Success. 

RETURN: = Carry set 
NotExistsErr The device driver is not currently loaded. 
Not SupportedErr The device driver is a ROM device driver and cannot be removed. 
InUseErr The device driver is currently open and cannot be removed. 
Error Error returned by the device driver. 


PANIC: None 


Remove the requested device driver of the name pointed to by ES:BX. 


The name here should be the same name which would be passed to the open services. Only device drivers 
in RAM can be removed by this service. DX specifies whether an LDD or a PDD device is to be removed. 
In both cases the remove vector will be executed before the device is deleted from memory. Calling this 
service will result in the DevHold and DevResume services being called. 


This service is used by the File Server to call the remove vector of a device driver before deleting it from 
memory. This service is restricted and should not be used by normal programs. Use the pevDelete service 
instead. 


DevQueryUnits Query the number of units 
ES:BX Pointer to the name of the device to be queried. 

RETURN: Carry clear 
AX The number of units supported by the device driver. 

RETURN: Carry set 
NotExistsErr Device driver not found. 


PANIC: None 
Queries the number of units supported by a device driver. 
This service only applies to LDDs. If the device driver is found, the number of units supported is returned 


in the AX register. A value of -1 implies an unlimited number of units. This is what is returned by the 
FIL: device driver as it can open a large number of files. 


DevFind Find all devices 
BX The find handle. 
Dx LDDSignature - LDD device type. 


PDDSignature - PDD device type. 
ES:DI Pointer to a wild card match string. 


DS:SI Pointer to the buffer to receive the name of the found device. 


7 DEVICE MANAGEMENT 


RETURN: = Carry clear 


AX The find handle for the next find. 
RETURN: Carry set 

NotExistsErr No more devices found. 
PANIC: 

PanicDevl Invalid device find handle. 


Finds all the devices installed of the type specified by DX which match the wild card string pointed to by 
ES:DI. 


DX is either pppsignature to find PDD devices or Lppsignature to find LDD devices. 


The device name written to DS:SI is a zero terminated string and MaxNameESize+2 bytes should be 
allowed for in the buffer. The first time this service is called, BX should be set to zero; the first device will 
be found. After a find, this service returns the find handle in the AX register. This find handle must be 
supplied on subsequent calls to this service to find the next device installed. 


No memory is used by this service and it can be abandoned at any time without taking any further action. 
The wild card string must always be supplied in ES:DI, and should be the same between calls to this 
service. 


DevVector Call a device vector 
CL The vector number to call. 
CH Moved to AH before the device vector is called. 
DI Device handle. 
BX Argument 1. 
DX Argument 2. 
SI Argument 3. 
RETURN: Carry clear 
AX The result from the device driver. 
RETURN: Carry set 
AL The error from the device driver. 
PANIC: 
PanicLib2 The device did not support the vector in CL. 


Given a handle to a device in DI, then the devices vector number in CL will be called. The value in CH is 
transferred to AH and the values in BX,DX,SI are passed to the device driver untouched. 


CHAPTER 8 


INPUT OUTPUT MANAGEMENT 


Devices and files 


As far as the I/O services are concerned, devices and files are exactly the same. The documentation just 
refers to devices, but wherever device is read, it may be interchanged for files. 


Thus the roopen service is used to open devices such as the RS232 device driver and files such as 
A:LETTERS.DOC. 


-WVE Sound file format 


Series 3a sound files contain a 32-byte header and a byte stream of digital sound. Such files normally have 
a.wve extension. During playback the byte stream is sampled and played at 8000 bytes per second (12-bit 
sound is converted to 8-bit using A-Law encoding). 


In C, the file header is represented by the following struct (defined in epoc.h) 


#define SignatureSize 16 
#define ALawSignature "ALawSoundFile**" 


typedef struct 
{ 
TEXT Signature[SignatureSize]; 
UWORD Version; 
ULONG Samples; 
UWORD SilenceInTicks; 
UWORD Repeats; 
UWORD Spare[3]; 
} SndFile; 


This header is written and read by the Series 3a sound services described below. The meanings of the 
items in the sndFile struct are: 


Signature 
The 16-byte (including the zero terminator) string "ALawSoundFile**". 
Version 


The Series 3a sound file version number as a 4-digit hexadecimal number of the form XYYZ, where X is 
the major release number, YY is the minor release number and Z is normally the hexadecimal digit F. 
This is the same version format as used by Genversion, for example. 


Samples 


The number of bytes following the header. This must always be the size of the file less the 32 bytes for the 
header. Dividing this by 8000 gives the duration of the sound in seconds. 


EPOC O/S SYSTEM SERVICES 


SilencelnTicks 


The number of system ticks of silence appended to each repeat on playback (in practice, you get at least 2 
ticks between repeats). 


Repeats 

The number of times to repeat the sound on playback (0 and 1 are the same). 
Spare 

Reserved for future use. 


A system tick is a 1/32th of a second, equivalent to 250 samples. 


loAsynchronous Asynchronous I/O 

AL 1/O function number. 

BX I/O handle. 

DS:CX Pointer to argument 1. 

DS:DX Pointer to argument 2. 

DS:DI Pointer to status word. 
RETURN: Carry clear 

AX Result from the device driver. 
RETURN: Carry set 

Error Depends on the device driver. 
PANIC: 

PanicIol Invalid I/O channel. 

PanicLibl Invalid library handle. 

PanicLib2 Invalid library function number. 


Request I/O services from device drivers. 


The I/O is asynchronous, i.e. the call will return immediately even if the I/O request has not completed. 
The value in AL can be one of the constants which start with the prefix toFunc. What functions are 
supported by a channel depends on the device driver originally opened. 


CX and DX are pointers to two parameters the meaning of which depends on the function being requested 
and the device driver that is open on the channel. DI is a pointer to a word which will contain the I/O 
completion status when the I/O completes. While the request is still being serviced this value will be 
PendingErr. 


If this service returns without an error then the device driver will always signal completion with one of the 
IoSignal, IoSignalByPid Of IoSignalByPidNoReSched Services. Thus, when waiting for the I/O request 
to complete, one of the loWaitForSignal OF IoWaitForStatus services should be requested, instead of 
polling the status word. 


loAsynchronousNoError Asynchronous I/O - no error reporting 


AL I/O function number. 
BX I/O handle. 

DS:CX Pointer to argument 1. 
DS:DX Pointer to argument 2. 
DS:DI Pointer to status word. 


RETURN: None 
PANIC: 
PanicIol 
PanicLibl 


PanicLib2 


8 INPUT OUTPUT MANAGEMENT 


Invalid I/O channel. 
Invalid library handle. 
Invalid library function number. 


This is exactly the same service as ToAsynchronous except that errors in starting the I/O request, instead 
of being reported by setting the carry flag, are reported by setting the status word and signalling. 


This service is provided as a convenience routine since many applications find it easier to handle starting 
errors as completion errors. In many cases there is no difference in the meaning for a given error and, 
therefore, no difference in action to be performed. 


loWithWait 


AL 
BX 
DS:CX 
DS:DX 

RETURN: = Carry clear 
AX 

RETURN: Carry set 
Error 

PANIC: 
PaniclIol 
PanicLibl 


PanicLib2 


Synchronous I/O 


1/O function number. 
I/O handle. 

Pointer to argument 1. 
Pointer to argument 2. 


Result from the device driver. 
Depends on the device driver. 
Invalid I/O channel. 


Invalid library handle. 
Invalid library function number. 


Request I/O services from device drivers synchronously. 


This service will return when the I/O request has completed. The value in AL can be one of the constants 
which start with the prefix toFunc. 


The functions supported by a channel depends on the device driver originally opened. CX and DX are 
pointers to two parameters whose meaning depends on the function being requested and the device driver 
that is open on the channel. 


loRoot Chain to root device 
DS:BX 1/O handle. 
DS:SI Pointer to the request packet. 
RETURN: Carry clear 
AX Result from device driver. 
RETURN: Carry set 
IoInvalidErr 1/O function requested is not valid for this device. 
PANIC: 
Paniclo2 Application requested the device to panic. 


If a root device driver does not support a particular I/O function then it should call this service (attached 
device drivers should call the tosuper function). 


DS:SI points to a structure of the type Rqznt. This service provides code which will respond to the 
following function requests: 


bd oFuncPanic 
e oFuncClose 
e oFuncCancel 
e oFuncAttach 
e oFuncDetach 


EPOC O/S SYSTEM SERVICES 


If the function number requested is not one of the above, then this service will return the loInvalidErr. 
This service should only be used by root device drivers. 


loSuper Chain to superclass device 
DS:BX 1/O handle. 
DS:SI Pointer to the request packet. 
RETURN: Carry clear 
AX Result from device driver. 
RETURN: Carry set 
IoInvalidErr I/O function requested is not valid for this device. 
Error Number Depends on the device driver. 
PANIC: 
PanicIol 1/O channel invalid. 


Requests I/O service from the device driver attached next on the I/O channel. 


This service allows an attached device driver to pass on I/O requests that the attached driver does not 
understand to the superclass device driver. 


DS:SI points to a structure of the type RqEnt. Note that the parameters are identical to those for the ToRoot 
service as the last device in the chain (root device driver) will eventually pass on any unknown requests to 
the ToRoot service. This service should only be used by attached device drivers. 


loWaitForSignal Wait for I/O completion 


None 

RETURN: None 

PANIC: 
PanicIol Channel invalid. 
PanicIo3 Handler invalid. 


When an application wants to wait for any of the outstanding asynchronous I/O requests to complete, it 
should call this service. 


After this service returns, one of the status words associated with the outstanding I/O requests is 
guaranteed to have changed from PendingErr to either a return result (i.e. 0 or positive) or another error. 
Even though this routine has no parameters it can still panic; after the signal has been received, this 
service will invoke any attached I/O handlers which have the ability to cause the process to be panicked. 


If an application wants to poll the status words, it cannot just look at the values in the status words. It 
must first give any handlers a chance to complete the I/O request. As a call to this service can suspend the 
process until one of the I/O requests completes, it is better to call the Ioyield service which is guaranteed 
to return after allowing the handlers to execute. 


loWaitForStatus Wait for specific request to complete 
DS:DI Pointer to status word of I/O request. 

RETURN: None 

PANIC: 
PanicIol Channel invalid. 
PanicIo3 Handler invalid. 


Waits for a specific I/O request to be completed. 


As long as the status word pointed to by DI has the value pendingErr, this service will continue waiting. 
As soon as the value changes then this service will return. 


8 INPUT OUTPUT MANAGEMENT 


loYield Poll for completion 
None 

RETURN: None 

PANIC: 
PanicIol Channel invalid. 
PanicIo3 Handler invalid. 


Update the status words of any I/O requests which may have completed. 


If an application wants to poll the status words, it cannot just look at the values in the status words. It 
must first give any handlers a chance to complete the I/O request. This service provides the mechanism to 
do this without suspending the process. 


loSignal Signal completion 


None 
RETURN: None 
PANIC: None 
Signals the completion of an outstanding asynchronous I/O request to the current process. 
All calls to a device driver through the toAsynchronous service, which are started successfully are 


balanced by a call to a signal service when they complete. Equally the application that requested the I/O 
must balance this signal with a call to the towaitForSignal service. 


loSignalByPid Signal completion by process ID 


BX The process ID to be signalled. 
RETURN: Carry clear 

Success. 
RETURN: = Carry set 

NoExistsErr The process does not exist. 


PANIC: None 


Signals the completion of an outstanding asynchronous I/O request to the process whose ID is in the BX 
register. 


All calls to a device driver through the toAsynchronous service which are started successfully are 
balanced by a call to a signal service when they complete. Equally the application that requested the I/O 
must balance this signal with a call to the towaitForSignal service. 


This service should not be used by device drivers in the interrupt part of their code because the interrupt 
service routine could be running under any process and a possible re-schedule that could occur would 
cause a stack build up. 


loSignalByPidNoReSched Signal completion, no reschedule 
BX The process ID to be signalled. 

RETURN: Carry clear 
Success. 

RETURN: = Carry set 
NoExistsErr The process does not exist. 


PANIC: None 


Signals the completion of an outstanding asynchronous I/O request to the process whose ID is in the BX 
register. 


If this service is used instead of toSignalByPid then the next re-schedule will only occur on the next time 
slice expiry. This may unnecessarily delay the signalled process. In order to overcome this, a re-schedule 
can always be forced by calling the TimsleepForTicks service with a value of 0. 


EPOC O/S SYSTEM SERVICES 


All calls to a device driver through the toAsynchronous service which are started successfully are 
balanced by a call to a signal service when they complete. Equally the application that requested the I/O 
must balance this signal with a call to the towaitForSignal service. 


This service should only be used by device drivers in the interrupt part of their code because the interrupt 
service routine could be running under any process and a re-schedule is to be avoided. 


loAddHandler Add a handler 


AL The vector number of the handler. 
BX Identifying data to be passed to the handler. 
DS, ES Must be pointing at the user process data space 
RETURN: Carry clear 
AX Handler handle. 
RETURN: Carry set 
IoAllocErr Not enough memory to add the handler. 


PANIC: None 
Adds a wait handler to the list of I/O handlers for that process. 


Whenever the IowaitForSignal service receives a signal, it will call all the active handlers for the 
process. The handler will be passed the channel handle passed in the BX register. When the handler is 
added, it will initially be disabled and in order to activate it, the device driver should call 
IoEnableHandler. Only device drivers should use this service. 


loRemoveHandler Remove a handler 
BX The handler handle. 
DS, ES Must be pointing at the user process data space 

RETURN: None 

PANIC: 
PanicIo3 Invalid handler handle. 


Removes a previously added wait handler from the process' list of I/O handlers. 


The handle in BX must be a handle returned from the toAddHandler service. Only device drivers should 
use this service. 


loEnableHandler Enable/Disable a handler 
BX The handler handle. 
CL 0 - To disable the handler. 
1 - To enable the handler. 
DS,ES Must be pointing at the user process data space 
RETURN: None 
PANIC: 
PanicIo3 Invalid handler handle. 


When a particular handler is first added to a list of handlers for a particular process, it is initially disabled. 
Thus, any signals which arrive will not cause the handler to be called. In order to enable the handler, this 
service must be called with CL set to 1. The handler indicates whether it wishes to remain enabled or be 
disabled on exit (see the section on device handlers). 


If asynchronous requests are cancelled, the handler may no longer be required to be called. The handler 
can be disabled by setting CL to 0. 


Devices should only keep their handlers enabled when they have outstanding requests to deal with; system 
performance would be significantly degraded if all handlers were permanently enabled. 


Only device drivers should use this service. 


8 INPUT OUTPUT MANAGEMENT 


loRequestReset Request a reset 
BX Device handle. 
cx Identifying data. 


RETURN: None 

PANIC: None 

Request the Supervisor to log a reset request for a device driver. 

When a channel is opened by a process, it is always possible that the process may be panicked or killed 


before it has a chance to close the channel. If this were to happen without the device driver knowing about 
it, the device would remain in use forever and the resource would be lost to the system. 


This service provides a mechanism for device drivers to be notified when the process which has opened 
the device has been terminated. It can then cleanup as necessary and mark itself no longer in use. 


The value passed in BX should be the device handle. This is passed in register DX by the device manager 
to the open and strategy vectors of a device driver. The value in CX is device dependent information to 
allow multiple unit device drivers to determine which unit should be reset. If the device is just a single 
unit device then it should place 0 in CX. 


This service should only be called by device drivers. 


loRequestResetCancel Cancel a requested reset 
BX Device handle. 
CX Identifying data. 


RETURN: None 
PANIC: None 


Request the Supervisor to cancel a reset request for a device driver. 


When a device is closed and the device driver has a reset request logged with the Supervisor, the 
outstanding request must be cancelled as it is no longer valid. 


The value in CX should always be exactly the same as the value passed to the toRequestReset Service, 
even if the device driver is a single unit device. 


This service should only be called by device drivers. 


loOpen Open a device 
ES:BX Pointer to the device name. 
Cx Open mode. 
Dx The I/O handle of an already opened device, if an attached driver is 
being opened. 
RETURN: Carry clear 
AX I/O handle. 
RETURN: Carry set 
Error Depends on the device being opened. 


PANIC: None 
Open a device driver for I/O. 


The name of the device is a zero terminated string. The open mode parameter in CX is device dependent 
and the relevant device driver documentation should be consulted. 


The open mode parameters for the filing system device driver are the constants starting with Mode. DX 
need only be set if opening a device driver which is an attached driver, in which case DX must be the 
handle of the already opened I/O channel to which the driver must be attached. 


EPOC O/S SYSTEM SERVICES 


loClose Close a device 
BX I/O handle. 

RETURN: Carry clear 
AX Result from device driver. 

RETURN: Carry set 
Error Depends on the device being opened. 


PANIC: None 


Close an open I/O channel. 


A zero value can be passed in BX and the service will just do nothing. This is useful as it allows zero to 
indicate a closed channel, especially in clean up situations. 


loRead Read from a device 
BX 1/O handle. 
DS:CX Pointer to buffer to receive the read data. 
Dx Number of bytes to read. 
RETURN: Carry clear 
AX Amount actually read. 
RETURN: Carry set 
Error Depends on the device being read. 


PANIC: None 


Read data from the device. 


The data read is written to the buffer pointed to by CX. Up to DX bytes will be read. The actual amount of 
data read is also returned in the DX register. If no error occurs then AX will have the same value as DX. 
If an error does occur then AL will have the error number and DX will contain the number of bytes read 
before the error occurred. 


loWrite Write to a device 
BX I/O handle. 
DS:CX Pointer to buffer to be written. 
Dx Number of bytes to write. 
RETURN: Carry clear 
AX Result from device driver. 
RETURN: Carry set 
Error Depends on the device being written. 


PANIC: None 
Write data to the device. 


DX bytes of data is written from the buffer pointed to by CX. 


loSeek Seek on a device 
BX I/O handle. 
CX SeekFromStart 


SeekFromEnd 
SeekFromCurrent 
SeekRecordSense 


SeekRecordSet 


SeekRewind 


Dx Pointer to a double word containing the new position. 


8 INPUT OUTPUT MANAGEMENT 


RETURN: Carry clear 


AX Result from device driver. 
RETURN: Carry set 
Error Depends on the device being "seeked". 


PANIC: None 


Perform a seek on a device. 


The type of seek to perform is as specified in the CX register and the new position is pointed to by the DX 
register. In most cases the seek position is a double word. 


loKeyAndMouseWithWait Mouse and keyboard 


DS:BX Pointer to a KeyEnt structure. 
RETURN: None 
PANIC: 
PaniclIo4 Another process is already waiting for an event. 


Get the next keyboard or mouse event into the keyEnt structure pointed to by BX. 


The system maintains a queue of up to 16 keyboard and mouse events in a buffer. If the buffer is not 
empty when this service is requested then it will return immediately with the event data copied to the 
structure at BX. If there is no event then the requesting task will be suspended until an event occurs. 


Four events are possible and more than one can be returned per call. The events are as follows: 
e Mouse valid. The mouse has been activated. (i.e. touched). 
¢ Mouse moved. The mouse has moved. 
e Mouse button state. The mouse button has changed state. 
e Key valid. A key has been pressed. 


Which event has occurred can be determined by consulting the keystate field in the returned structure. 
This service can only be requested by a task and not a process. There is usually only one task in the 
system, usually of the window server, which calls this service and then distributes the events to all other 
processes. 


loAddApplicationHandler Add an application handler 


BX Identifying data to be passed to the handler. 

cx Address of the application handler. 

Dx Address of the application handler dispatcher. 

DS, ES Must be pointing at the user process data space 
RETURN: Carry clear 

AX Handler handle. 
RETURN: Carry set 

IoAllocErr Not enough memory to add the handler. 


PANIC: None. 
Adds an application wait handler to the list of I/O handlers for that process. 


Whenever the IowaitForSignal service receives a signal, it will call all the active handlers for the 
process. 


The channel handle in register BX will be passed to the application handler dispatcher in register AX 
while the handler's address will be passed in register BX. 


The dispatcher should execute a CALL BX to run the handler and then execute a RET FAR. 


When the handler is added, it will initially be disabled; in order to activate it, 
ToEnableApplicationHandler should be called. 


EPOC O/S SYSTEM SERVICES 


loRemoveApplicationHandler Remove an application handler 
BX The handler handle. 
DS, ES Must be pointing at the user process data space 

RETURN: None 

PANIC: 
PanicIo3 Invalid handler handle. 


Removes a previously added handler from the process' list of I/O handlers. The handle in BX must be a 
handle returned from the toaddApplicationHandler Service. 


loEnableApplicationHandler Enable/Disable application handler 


BX The handler handle. 
CL 0 - Disable the handler. 
1 - Enable the handler. 
DS,ES Must be pointing to the user process data space 
RETURN: None 
PANIC: 
PanicIo3 Invalid handler handle. 


When a particular handler is first added to the list of handlers for the process, it is initially disabled. Thus 
any signals which arrive will not cause the handler to be called. In order to enable the handler, this service 
must be called with CL set to 1. 


The handler indicates whether it wishes to remain enabled or be disabled on exit (see the section on device 
handlers). If asynchronous requests are cancelled, the handler may no longer be required to be called; the 
handler can be disabled by setting CL to 0. 


Handlers should only be enabled when they have outstanding requests to deal with as system performance 
would be significantly degraded if all handlers were permanently enabled. 


loShiftStates Get the shift states 


None 
RETURN: 

AX The current shift states. 
PANIC: None 


This service will return the current shift states. 


It is valuable to enquire on the status of the CAPS lock and the NUM lock states when the system first 
powers up. 


loWaitForSignalNoHandler Wait for |/O completion no handlers 


None 

RETURN: None 

PANIC: 
PanicIol Channel invalid. 
PanicIo3 Handler invalid. 


This service is identical to towaitForSignal except that no handlers are allowed to run. This is valuable 
for tasks which are waiting for a signal as the normal service would run the handlers belonging to the 
parent process of the task, a bad mistake! 


Recall that a task is a subsidiary process that shares the same data segment as the parent process; because 
a task can never have a handler, there is never any problem in calling this service. 


8 INPUT OUTPUT MANAGEMENT 


loSignalKillAsynchronous Request signal from Supervisor 
BX The process ID, which will trigger the signal, when it terminates. 
DI The status word to be cleared on completion. 


RETURN: Carry clear 
Success 
RETURN: = Carry set 
NotExistsErr The requested process does not exist. 
PANIC: None 
Notifies the supervisor to send a signal to the process calling this service when the process specified in BX 


exits or is panicked. 


This service is very similar to MessSignal in that it is a mechanism which allows processes to perform 
valuable housekeeping when another process terminates. 


When the process specified in BX terminates, a signal will be sent from the supervisor and the status word 
will contain the reason code for termination. 


Having registered an interest in a process with the supervisor, this interest may be cancelled by calling the 
IoSignalKillCancel service. This stops the supervisor from sending a signal on termination of that 
process. 


loSignalKillCancel Cancel requested signal from Supervisor 


BX The process ID which will trigger the signal, when it terminates. 
RETURN: Carry clear 
Success. 
RETURN: = Carry set 
NotExistsErr The process has no signal request logged with the supervisor. 
PANIC: None 


Cancels a previously requested signal from the supervisor. The status word will be updated to cancelzrr 
and a signal will be sent from the supervisor. 


loNextHalfSecond Request signal on next half second 


None. 
RETURN: 
None. 
PANIC: 
None. 
Requests a signal to be sent when the next exact half second expires. 


Unlike other asynchronous requests there is no status word associated with this call as it is held internally 
by the operating system. 


Completion can be polled for in the normal way by calling 1oNextHalfSecondstatus which will return 
either PendingErr, FailErr Or a positive non zero integer. PendingErr will be returned if the request has 
not yet completed. railzrr is returned if the system time has changed or the machine has been switched 
off. A positive non-zero integer represents the number of half seconds since the last request was 
completed. 


This service is NOT to be used by any applications; it is reserved for use by the window server to keep 
itself synchronised with the system clock with the minimum system overhead. 


EPOC O/S SYSTEM SERVICES 


e loNextHalfSecondStatus Query completion of loNextHalfSecond 


None. 
RETURN: 
AX The completion status. 
PANIC: 
None. 


This function will return either PendingErr, FailErr Or a positive non-zero integer. PendingErr will be 
returned if the request has not yet completed. raiizrr is returned if the system time has changed or the 
machine has been switched off. A positive non-zero integer represents the number of half seconds since 
the last request was completed. 


This service is NOT to be used by any applications; it is reserved for use by the window server to keep 
itself synchronised with the system clock with the minimum system overhead. 


©loPlaySoundW Play back sound file synchronously 


BX Pointer to the sound file name. 
cx The duration in ticks or zero if supplied in the file. 
Dx The sound volume to be used. 
RETURN: 
FailErr Sound is disabled. 
Other errors File system errors in general. 


PANIC: None 
Play back a sound file synchronously. 


The string at BX should be either the file specification of the sound file which is simply parsed with a 
.wve extension or it should begin with a * character followed by just the name component of the sound 
file. 


If the string starts with a * character, the extension .wve is assumed and the service automatically hunts 
ROM:: and the \wve directories of M:, A: and B: (in that order). Note that the Series 3a ROM:: sound files 
have names sys$al01.wve, sys$al02.wve, etc. 


CX specifies the duration in system ticks that the sound file will play. If the absolute value is shorter than 
the natural duration of the sound file then playback will be truncated; if greater than the natural duration 
then playback will be padded with trailing silence. 


Note that the natural duration includes any trailing silence and the number of repeats that are specified in 
the file header. 


DX specifies the playback volume between 0 and 5 inclusive, with 0 the loudest. On the Series 3a there 
are only 4 actual volume levels: (0,1), 2, 3, (4,5). 


The format of the sound file header is described at the beginning of this chapter. 


This service fails with railzrr if sound is disabled. 


©loPlaySoundA Play back sound file asynchronously 
BX Pointer to the sound file name. 
cx The duration in ticks or zero if supplied in the file. 
DX The sound volume to be used. 
DI Pointer to the status word. 
RETURN: 
None. 


PANIC: None 
Play back a sound file asynchronously. 


8 INPUT OUTPUT MANAGEMENT 


The string at BX should be either the file specification of the sound file which is simply parsed with a 
.wve extension or it should begin with a * character followed by just the name component of the sound 
file. If the string starts with a * character, the extension .wve is assumed and the service automatically 
hunts ROM:: and the \wve directories of M:, A: and B: (in that order). Note that the Series 3a ROM:: 
sound files have names sys$al01.wve, sys$al02.wve, etc. 


CX specifies the duration in system ticks that the sound file will play. If the absolute value is shorter than 
the natural duration of the sound file then playback will be truncated; if greater than the natural duration 
then playback will be padded with trailing silence. 


Note that the natural duration includes any trailing silence and the number of repeats that are specified in 
the file header. 


DX specifies the playback volume between 0 and 5 inclusive, with 0 the loudest. On the Series 3a there 
are only 4 actual volume levels: (0,1), 2, 3, (4,5). 


During playback the status word at DI contains pendingErr. On completion of playback, the status word 
contains the completion status which will be zero if playback completed successfully or cancelzrr if 
cancelled using IoPlaySoundCancel or a negative error number. 


The format of the sound file header is described at the beginning of this chapter. 


This service fails with error FailErr if sound is disabled. 


©loPlaySoundCancel Cancel play back of sound file 


None 
RETURN: 

None. 
PANIC: None 


Cancel playing back a sound that was initiated using 1oPlaySounda. 


After a call to toplaySoundCancel, the completion status of toplaySounda will be cancelErr. 


©loRecordSoundW Record sound to a file synchronously 
BX Pointer to the sound file name. 
CX Sound file length in 2048-byte units. 
RETURN: 
FailErr Sound is disabled. 
VolumeErr Cannot record to a Flash SSD. 
Other errors File system errors in general. 


PANIC: None 


Record a sound to file synchronously. 


The file may not be on a Flash SSD. The register BX points to a string containing the name of the sound 
file. By default, the extension is .wve. Sound will be recorded to this file which will be replaced if it 
already exists. 


CX specifies the number of bytes to be recorded in 2048-byte units, excluding the 32 byte header. A value 
of 4 (8K) in CX corresponds to approximately one second. Before recording starts, a file of length 
32+cx*2048 bytes is created so this amount of space must exist on the disk. 


The format of the sound file header is described at the beginning of this chapter. 


This service fails with railerr if sound is disabled. 


EPOC O/S SYSTEM SERVICES 


©loRecordSoundA Record sound to a file asynchronously 
BX Pointer to the sound file name. 
cx Sound file length in 2048-byte units. 
DI Pointer to the status word. 


RETURN: None. 

PANIC: None 

Record a sound to file asynchronously. 

The file may not be on a Flash SSD. The register BX points to a string containing the name of the sound 


file. By default, the extension is .wve. Sound will be recorded to this file which will be replaced if it 
already exists. 


CX specifies the maximum number of bytes to be recorded in 2048-byte units, excluding the 32 byte 
header. A value of 4 (8K) in CX corresponds to approximately one second. Before recording starts, a file 
of length 32+cx*2048 bytes is created so this amount of space must exist on the disk. 


During recording the status word at DI contains pendingErr. On completion, the status word contains the 
completion status which will be zero if recording completed successfully, or cancelErr if cancelled using 
IoRecordSoundCancel, or a negative error number. 


The format of the sound file header is described at the beginning of this chapter. 


This service fails with railzrr if sound is disabled and volumeErr on attempting to record to a Flash 
SSD. 


©loRecordSoundCancel Cancel recording sound to a file 


None 
RETURN: None. 
PANIC: None 
Cancel recording sound to a file that was initiated using ToRecordSounaa. The sound file is truncated to 
the actual length that was recorded before cancellation. 


After a call to toRecordSoundCancel, the completion status of toRecordSounda Will be cancelErr. 


8 INPUT OUTPUT MANAGEMENT 


Input Output Management update 


The majority of the additional EPOC I/O management system services described in this section were 
introduced for the Series 3c and Siena. 


With the exception of the HC, all the services are, in principle, available on any machine that contains 
EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in 
this section should generate an =_GEN_NsuP error. 


Some services require the presence of hardware that is not built into all machines in the SIBO range. If 
the relevant hardware is not present on a particular machine, calling the service will either have no effect 
or return an error of E_GEN_Nsup. The descriptions of such services contain a list of the machines on 
which they are intended to be used. 


loPlaySoundAO Asynchronous partial sound file replay 
BX Pointer to full file specification 
cx Required duration, in ticks 
Dx Playback volume 
DI Pointer to a status word 
SI Offset, in ticks 
RETURN: 
DI Pointer to status word 


PANIC: None 


This service is only available on Series 3c machines. 
Play back a selected section of a sound file asynchronously. 


The string at BX should be either the file specification of a sound file, which is simply parsed with a .wve 
file extension, or it should begin with a * character, followed by just the name component of the sound 
file. 


If the string starts with a * character, the extension .wve is assumed and the service automatically hunts 
ROM:: and the \wve directories of M:, A: and B: (in that order). Note that the Series 3a and Series 3c 
ROM sound files have names sys$al01.wve, sys$al02.wve, etc. 


DX specifies the playback volume, which should be in the range 0 to 5 inclusive, with 0 being the loudest. 
There are only four actual sound levels: (0,1) 2, 3, (4,5). 


SI specifies the offset, in ticks, from the start of the sound to the point at which replay will start. 


CX specifies the duration in system ticks for which the sound will play. If this duration is less than the 
remaining natural duration of the sound from the specified starting point, playback will be truncated to the 
specified duration. If the specified duration exceeds the remaining natural duration of the sound then 
playback will be padded with trailing silence. 


Note that the natural duration includes any trailing silence and the number of repeats that are specified in 
the file header 


During playback the status word at DI contains pendingErr. On completion of playback, the status word 
contains the completion status, which will be zero if playback completed successfully, cancelErr if 
playback was cancelled by the use of toPlaySoundcancel, or a negative error number. 


This service fails with railerr if sound is disabled. 


CHAPTER 9 


FILE MANAGEMENT 


The file server 


The file server is a separate process which runs whenever an application process needs to access any of the 
filing systems. 


The server program provides a mechanism to serialise access to the resources of the filing systems in the 
same way as the window server serialises access to the screen, keyboard and mouse. 


By default a process does not have any access to the filing system. If the process requires access, then it 
must tell the file server program of its presence by using the Filconnect service. Once established, the 
connection cannot be broken throughout the life of the process. 


Many of the services such as DevopenPpp make requests to the file server and, as such, require that the 
process has first made connection with the server. If the connection has not been made then the process 
will be panicked. 


FilConnect Connect to the file server 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
RETURN: None 
PANIC: 

PanicFilel Already connected to file server. 


Connects the process to the file server. 


Any process requiring access to the filing system must connect to the server by using this service before 
calling any of the other services in the File manager or in the I/O manager. 


It is only necessary to connect to the server once; the connection can be established at any time. 


FilExecute Execute an image file 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


DS:DX If AL is non-zero then DX points to the status word. 

ES:BX Pointer to the path name of the image file to be executed. 
DS:CX Pointer to the command line argument. 

DS:DI Pointer to a word to receive the handle of the executed process. 


EPOC O/S SYSTEM SERVICES 


RETURN: Carry clear 


Success 

RETURN: = Carry set 
NameErr Invalid file name. 
DeviceErr Invalid device specification. 
ImageErr Invalid image file format. 
NotExistErr Image file does not exist. 
NoProcessErr No process slots available. 
Others Various other I/O errors. 


PANIC: None 


Creates a process in memory from the contents of the image file specified by the BX register. 


The process created will have the same name as the name of the image file. Before the new process will 
run, it must be resumed using the procResume service, passing it the handle as returned in the word 
pointed to by the register DI. If a process of the same name as that of the file name is already running in 
memory then the new process will share the code segment of the running process and only the data 
segment of the new process will be loaded from the image file. 


If CX is zero then no command line will be passed to the executed process. If CX is non-zero then it 
should point to a byte counted command buffer. The address will be passed to the executed routine. 

The buffer is byte counted so that binary data can be passed in the command line. The maximum length 
of the command line is MaxcommandBuf fer bytes. The executed process will be given a command line 
allocated in its heap which consists of the full path used to find the image file followed by the data 
pointed to by CX. 


FilParse Parse a file name 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Input file name string. 
cx Related file specification string. 
DI Pointer to a buffer to receive the parsed file name. 
SI Pointer to a FullParseEnt buffer to receive the parse information 
block. 
RETURN: Carry clear 
Success 
RETURN: = Carry set 
NameErr Invalid file name. 
DeviceErr Invalid device specification. 


PANIC: None 


The parse service provides an equivalent service to that in PLIB. 


This service requires that the process be connected to the file server. The current directory and device will 
provide the defaults if a complete related file specification is not provided. 


FilPathGet Get current path 


AL Zero - Synchronous request. 


Non-Zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Pointer to buffer to receive the path. 

RETURN: Carry clear 
Success 


9 FILE MANAGEMENT 


RETURN: = Carry set 
AL The error number. 
PANIC: None 


This service gets the current path of the process. This path is the default for all file services if no path is 
specified. 


FilPathSet Set current path 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the new path name. 
RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL The error number. 


PANIC: None 


This service sets the current path of the process. The path must be valid at the time of setting. 


FilPathTest Test path available 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the path name to be tested. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
AL The error number. 


PANIC: None 


This service tests that the path referenced in register BX is available; in other words it checks that it 
exists. 


FilDelete Delete a file or directory 

AL Zero - Synchronous request. 

Non-zero - Asynchronous request. 

Dx If AL is non-zero then DX points to the status word. 

BX Pointer to the name of the file or directory to be deleted. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

NameErr Invalid file name. 

ExistsErr Directory is not empty. 

LockedErr File or directory protected from delete. 

NotExistsErr File or directory does not exist. 

DirErr Invalid path specification. 


PANIC: None 
Delete the file whose name is pointed to by BX. 


The name can specify a file or a directory. If a directory is specified then it must be empty before it can be 
deleted. 


EPOC O/S SYSTEM SERVICES 


FilRename Rename a file or directory 
AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the old name of the file or directory to be renamed. 
cx Pointer to the new name of the file or directory to be renamed. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
NameErr Invalid file name. 
ExistsErr New file or directory already exists. 
NotExistsErr Old file or directory does not exist. 
DirErr Invalid path specification. 
DeviceErr Attempt to rename across devices. 


PANIC: None 


Rename the file whose name is pointed to by BX to the name pointed to by CX. The name can specify a 
file or a directory. 


FilStatusGet Get file or directory status 
AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the name of the file or directory. 
cx Pointer to a FileStatusEnt structure. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
NameErr Invalid file name. 
NotExistsErr File or directory does not exist. 
DirErr Invalid path specification. 


PANIC: None 
Get the status of the file whose name is pointed to by BX. The name can specify a file or a directory. 


The status information is written to a FileStatusEnt structure pointed to by CX. This structure is defined 
as: 


FileStatusEnt struc 


FileVersionNo dw 2 
FileAtt dw e 
FileSize dd ? 
FileModDate dd 2. 
FileSpare db 4 dup (?) 


FileStatusEnt ends 


and is equivalent to the PLIB p_rnro struct. 


FilStatusSet Set file or directory status 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the name of the file or directory. 

CX Mask of status bits to set. 

DI Value of status bits. 


9 FILE MANAGEMENT 


RETURN: Carry clear 


Success 

RETURN: = Carry set 
NameErr Invalid file name. 
NotExistsErr File or directory does not exist. 
DirErr Invalid path specification. 


PANIC: None 
Sets the status of the file whose name is pointed to by BX according to the bits set in CX and DI. 


If a bit is set in the CX register the appropriate bit in DI will be used. The name can specify a file or a 
directory. The bits correspond to the rileatt flags. 


FilStatusDevice Get device status 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the name of the device. 
CX Pointer to a DeviceStatusEnt Structure. 


RETURN: Carry clear 

Success 
RETURN: = Carry set 

DeviceErr Invalid device name. 
PANIC: None 


Get the status of the device whose name is pointed to by BX and write this information into the 
DeviceStatusEnt structure pointed to by CX. This structure is defined as: 


DeviceStatusEnt struc 

DeviceVersionNo dw ? 

DeviceMediaType dw ? 

DeviceIsRemovable dw ? 

DeviceStatusSize dd ? 

DeviceStatusFree dd ? 

DeviceStatusName db MaxVolumeName dup _ (?) 
DeviceBatteryState dw ? 

DeviceSpare db 16 dup (?) 
DeviceStatusEnt ends 


where MaxVolumeName has the value 32. This structure is equivalent to the PLIB p_p1nro struct. 


FilStatusSystem Get file system status 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the name of the file system. 
CX Pointer to a NodeStatusEnt structure. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL Error value. 


PANIC: None 


EPOC O/S SYSTEM SERVICES 


Write the status of the file system whose name is pointed to by BX into the nodestatusEnt structure 
pointed to by CX. This structure is defined as: 


NodeStatusEnt struc 

NodeVersionNo dw ? 
NodeType dw ? 
NodeSupportsFormat dw ? 
NodeStatusSpare db 26 dup (?) 
NodeStatusEnt ends 


and is equivalent to the PLIB p_ninro struct. 


FilMakeDirectory Make a new directory 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to new directory name. 
RETURN: Carry clear 


Success 

RETURN: Carry set 
ExistsErr Directory already exists. 
DeviceErr Invalid device name. 
NameErr Invalid path name. 


PANIC: None 


Makes a new directory using the name pointed to by BX. 


If the path to the directory does not exist then the full path will be made. 


FilOpenUnique Open a unique file name 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
ES:BX Pointer to related file specification. 
Cx Open mode. 
RETURN: Carry clear 
AX 1/O handle. 
RETURN: Carry set 
FailErr Failed to get a unique file name. 
Errors Dependent on the filing system. 


PANIC: None 

Open a unique file name. 

The related file name pointed to by BX is used only for its path in order to generate the unique file name. 
If a unique file name is successfully opened then the name of the file is written back to the buffer pointed 


to by BX. The open mode parameter in CX should only specify the format and access fields as the file 
will always be opened with ModeCcreate and ModeUpdate. 


FilSystemAttach Attach a file system 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 


BX Pointer to a file system PDD. 


9 FILE MANAGEMENT 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL Error value. 


PANIC: None 
Attaches a file system PDD to the file server. 


FilSystemDetach Detach a file system 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to a file system name. 
RETURN: Carry clear 


Success 
RETURN: Carry set 
AL Error value. 


PANIC: None 


Detaches a file system from the file server. The built in file systems cannot be detached. 


FilPathGetByld Get current path by ID 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Process ID whose path is required. 
cx Pointer to buffer to receive the path. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL The error number. 


PANIC: None 


This service gets the current path of the process whose ID is specified in BX. The path is copied into the 
buffer pointed to by CX. 


FilChangeDirectory Change directory 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 

BX Pointer to file or directory name string. 

CX Pointer to buffer to receive the new file/dir name string. 

DI Mode of changing directory. 

SI Pointer to sub directory name if DI is FileChangeDirSubdir. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL The error number. 


PANIC: None 


EPOC O/S SYSTEM SERVICES 


This service allows a path name to be manipulated. No assumptions about file names are made. The root, 
parent or sub directory may be requested. 


FilSetinitialPath Set initial path 


AL Zero - Synchronous request. 
Non-zero - Asynchronous request. 
Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the new initial path name. 
RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL The error number. 


PANIC: None 


This service sets the initial path given to a process when it connects to the file server. This service has no 
effect on processes already connected. 


FilSetFileDate Set file date 


AL Zero - Synchronous request. 


Non-zero - Asynchronous request. 


Dx If AL is non-zero then DX points to the status word. 
BX Pointer to the file path name. 
DI:CX New file date in seconds. 


RETURN: Carry clear 


Success 
RETURN: Carry set 
AL The error number. 


PANIC: None 


Sets the time and date for a file. CX is the least significant word and DI is the most significant word of the 
date and time in seconds. 


FilLocChanged Local file system changed 
BX The bit mask for the changed channels 

RETURN: 
AX The bit mask for any changed channels 


PANIC: None 


This service reports on whether the local file system has changed since the last time it was called. 


Because independent software routines may require this service, up to 15 channels are provided. Each 
channel is a single bit in the register BX passed to this service and the corresponding bit in the result in 
register AX. The bits available are 0-14, the top bit being unavailable to ensure that a negative error can 
still be returned. 


Bits 8-14 are reserved for system components and should not be used by any application. An application is 
free to choose any other bit in the range 0-7. Normally bit 0 would be used. 


BX is loaded with | and the function called. If 0 is returned then the file system has not changed. If 1 is 
returned then it has changed. Note that the very first time this service is called, it is guaranteed to return 
changed. If BX is loaded with 2 and the file system has changed then AX will return 2. 


Change as far as the file system is concerned is anything which would cause directory information on the 
file system to change but not alterations to an actual file. This service allows programs displaying file lists 
to update them automatically if any changes occur (such as changing the SSD or deleting a file). 


©FilLocDevice 


AL 


DX 
BL 
Cx 
RETURN: Carry clear 
Success. 
RETURN: = Carry set 
NotReadyErr 
DeviceErr 


NotSupportedErr 


UnknownErr 


PANIC: None. 


9 FILE MANAGEMENT 


Read media information of a local device 


Zero - synchronous request. 

Non-zero - Asynchronous request. 

If AL is non-zero then DX points to the status word. 
The local device. 


Pointer to a word to take the media type. 


The device is not available. 
The device BL is invalid. 


No PDD exists which can 
handle the device. 


Read media information of a local device (that is, a device on LOC::) specified by BL. The value of BL 
must be one of the ASCII characters 'M' or 'T' or lie in the range 'A' to 'H' inclusive where 'T' (Internal) is 


an alias for 'M'. 


Apart from two additional flags, the value written to the word at CX is the same as the value written to the 
DeviceMediaType field of the pevicestatusEnt structure using the FilstatusDevice system service. 
These two extra flags are Batteryvalid and BatteryGood defined in osloc.inc. If Batteryvalid 1s not set 
then the device does not support battery measurement. If Batteryvalid is set, then BatteryGood will be 
set if the voltage is good or clear if it is too low. 


Note that the media does not have to be mountable for this service to work. 


©FilLocReadPdd 


AL 


DX 


RETURN: Carry clear 
Success. 
RETURN: = Carry set 


OsErr 


CorruptMediaErr 


PANIC: None. 


Read a local device directly 


Zero - synchronous request. 

Non-zero - Asynchronous request. 

If AL is non-zero then DX points to the status word. 
The local device. 

Pointer to a double word SSD position. 

Number of bytes to read. 

Pointer to buffer to take the data read. 


The medium is not mounted. 


The specified position is greater than the size of the SSD. 


Read data directly from a given offset on a local device (that is a device on LOC: :) into the buffer 


provided. 


BL specifies the device and must be one of the ASCII characters 'M' or 'T' or lie in the range 'A' to 'H' 
inclusive where 'T' (Internal) is an alias for 'M'. CX points to a double word (4-byte) device offset. SI is the 
number of bytes to be read into the buffer at DI. The data is read very efficiently as it is performed by a 
direct access to the physical device driver (PDD). 


The medium must have been mounted prior to using this service. To ensure that the medium is mounted, 
make any normal device access (e.g. call service FilstatusDevice). 


CHAPTER 10 


PROCESS MANAGEMENT 


The process ID and names 


In this chapter the following terms are all used to mean the same thing: 
e process handle. 
e process ID. 
e pid. 


All processes in the system are known by their ID. Many of the services return the process ID but often 
only the name of the process is known. 


It is necessary to determine the ID of a process before services requiring an ID can be used. This can be 
accomplished by calling the procIdByName service. 


There is an additional complication due to the fact that multiple instances of the same program can be 
running at any one time. The operating system overcomes this by giving each process a different number 
as part of its name depending on which process control block that it occupies. Processes have names of up 
to eight characters followed by a period, a $ and a two digit number. 


If a program called sort is executed twice, the process names might be as follows: 
e SORT.$07 
e SORT.$11 


Since a program cannot know in advance the number part of a process name, the ProcIdByName service 
allows a wild card match string. Thus to find the process ID of the first sort process the string should be 
"SORT.*". Of course, only the first process would be found. If it is required to find all the sort processes 
the ProcFind service can be called repeatedly to enumerate all the matching processes. 


Process scheduling 


Epoc/Os is a time slice, multi-tasking operating system which schedules processes to run on the basis of 
their priorities. 


A fixed time slice is given after every re-schedule which will be used by the process until it is all used up 
or the process gives up the CPU (e.g. when waiting for an I/O request to complete). 


At any one time, only the highest priority process available to run will execute. All other lower priority 
processes are effectively blocked until the higher priority process gives up the CPU. 


If two or more processes share the highest priority, each process will be executed on a round robin basis, 
for a time slice each. 


If a higher priority process becomes available to run at any time, the lower priority process will be 
pre-empted and it will lose its time slice. 


Priorities are unsigned byte values in the range | to 255. The operating system reserves the values in the 
range | to cPBMinPriority-l and cPBMaxPriority+l to 255. The supervisor runs at priority 248 while the 
file server runs at priority 240. 


It is worth noting that interrupts run at the same priority as the process that they interrupt. 


10-1 


EPOC O/S SYSTEM SERVICES 


i 
Process control 


Often it is necessary for a process to be concerned about the presence of other processes in the system. For 
example, servers need to tidy up resources after processes which have connected to the server terminate 
before releasing the resources they own. 


The services MessSignal,IoSignalKillAsynchronous, MessSignalCancel and ToSignalKillCancel are 
specially designed to help in tracking a process in the system. 


If a process has logged on an interest in a process then it will receive a message or an I/O signal, when the 
process terminates. The message or status word will contain the reason code for the process terminating. 


Process ID and process table address 


The process ID consists of two components in a 16 bit value. 


The first component occupying the 4 most significant bits is a value in the range 0 - 7 which is allocated 
by the operating system each time a process is created, and serves to uniquely identify the process. 


The second component occupies the remaining 12 bits of the ID and is the offset in the operating system's 
data segment of the process control table. There is a lot of valuable information available in the process 
control table which can be retrieved using the GenGetOsData service. There is a mask declared PidMask 
which will mask out the address portion from the ID, suitable for use as the address to retrieve the process 
control data. 


Terminate and Kill 


There are two services which can be called to stop a process from running, ProcTerminate and Prockill. 


In certain types of applications it may be necessary for some cleanup code to be executed before the 
application actually exits. In these cases the process can register with the proconTerminate Service that it 
should be sent a message in response to the procTerminate request. It is then up to the application to 
detect the message, do the necessary cleanup code and then kill itself by calling prockill. 


If a process is terminated with procTerminate and it has not registered a proconTerminate then the 
operating system just calls prockill. 


ProcKill will always destroy the application regardless of whether the application has registered a 
message with the proconTerminate Service or not. 


ProcTerminate is the recommended method of stopping a process as it allows any process which does 
have cleanup code to execute the cleanup code on exit. If you are paranoid then a time out can be set up 
after the ProcTerminate service and if the process has not terminated then the prockill service can be 
called to definitely remove the process. 


Procld Get the current process ID 


None 
RETURN: 

AX Current process handle. 
PANIC: None 


Returns the ID of the process which calls this service. 


10-2 


10 PROCESS MANAGEMENT 


ProcldByName Get a process ID by name 
ES:BX The process name. 

RETURN: Carry clear 
AX Process handle. 

RETURN: Carry set 
NotExistsErr The process does not exist. 


PANIC: None 


Returns the ID of a process corresponding to the name pointed to by BX. The name is a zero terminated 
string which may contain wild cards. 


ProcGetPriority Get a process priority 
BX The process handle. 
RETURN: Carry clear 
AL Process priority. 
RETURN: Carry set 
NotExistErr The process does not exist. 
PANIC: 
PanicProcl Invalid process ID. 


Returns the priority of the process specified in BX. The priority is returned in register AL. 


ProcSetPriority Set a process priority 
BX The process handle. 
AL The new priority. 


RETURN: Carry clear 


Success. 
RETURN: = Carry set 

RangeErr Priority was invalid. 

NotExistErr The process does not exist. 

FailErr Tried to set the priority of the null, supervisor or file server process. 
PANIC: 

PanicProcl Invalid process ID. 


Set the priority of the process specified in BX to the new priority value specified in register AL. The 
priority in AL must lie between the limits cpBMinPriority and cpBMaxPriority inclusive. Calling this 
service will cause a re-schedule. It is not possible to change the priority of the null, supervisor or file 
server processes. 


ProcGetOwner Get the owning process 
BX The process handle. 
RETURN: Carry clear 
AX The owning process PID. 
RETURN: Carry set 
NotExistErr The process does not exist. 
PANIC: 
PanicProcl Invalid process ID. 


This service returns the PID of an owning process. The ID of the process whose owner is being sought, is 
passed in register BX 


EPOC O/S SYSTEM SERVICES 


The window server uses this service when a foreground process dies to determine which process should be 
brought to foreground next. For example if the system launches a program and it exits, the system will 
return to foreground. If the program, however, runs an OPL program which exits, the program will return 
to foreground. 


Note that the owning process need not be running. You can check this by calling something harmless, 
such as ProcGetPriority on the returned PID in AX. 


ProcCreate Create a process 
ES:BX Pointer to the create process block. 

RETURN: Carry clear 
AX Process handle. 

RETURN: Carry set 
NameErr Not a valid process name. 
ExistsErr A different process of the same name is already running. 
NoProcessErr No more process slots. 
ArgumentErr The size of data+stack+heap was greater than OxFFE paragraphs. 


PANIC: None 


This is the basic create process service. 


The information required to create a process is in the control block pointed to by BX. The control block 
must have the structure cpBlock. The create service leaves the process suspended and procResume should 
be called to start the process executing. 


This service should not be called directly by an application. Instead, the higher level Filzxecute service 
should be called; ri1zxecute will itself call this service at some point. 


Because code segments can be shared and the key to shared code segments is the name of the process 
running, it is important to ensure that two images which are different but which have the same name are 
not run simultaneously. To this end a checksum of the code segment is remembered and if a request is 
made to start a new process of the same name as one already running their checksums are compared. If 
they are the same then the new process will share the already loaded code segment. If they are not then the 
ExistsErr Will be returned. This error can also be returned from the FilExecute service. 


ProcCreateTask Create a task 
DS:BX Pointer to the task name. 
CL Task priority. 
SS:DI Pointer to top of stack in current process' data segment. 
CS:SI Pointer to task code in the current process’ code segment. 
RETURN: Carry clear 
AX Process handle. 
RETURN: Carry set 
NameErr Not a valid process name. 
NoProcessErr No more process slots. 
PANIC: 
PanicProc3 Task tried to create a task. 


A task is a process just like any other process with the special property that it shares its data segment with 
an owning process. Since it shares the data space of the owning process, it can clearly access all the data 
belonging to the parent which makes communication with the parent very easy. Because it is still a 
separate entity in its own right, it needs its own stack in the data space of the parent (which is passed in 
DI). Clearly the parent and the task must co-operate closely when accessing the data in the data segment 
or unpredictable results will occur. 


10-4 


10 PROCESS MANAGEMENT 


Imagine a spreadsheet program which must often go away for long periods of time to re-calculate all the 
formulae when a value is changed. While the re-calculation is being executed by the process it cannot be 
looking for user input, so the program appears to go dead for a while. The traditional way to overcome 
this problem is to poll the keyboard every now and then to see if there is some input requiring processing 
and if there is, to abandon the re-calculation to process the new input. Using tasks, it is much easier just 
to have a task to do the job of re-calculation. When the parent process needs the data re-calculating, it just 
resumes the task, which will immediately start the re-calculation and then wait either for the task to finish 
or for more input to arrive. When the task has completed its work it can simply suspend itself until needed 
again. By having the task at a lower priority than the parent process, the re-calculation will always be 
halted allowing the parent process to deal with fresh input. 


A process can create as many tasks as it has stack space available and there are process slots free in the 
system. Remember that a task is still a process. If a task is panicked then the parent process will be 
panicked as well. If the parent process terminates, then the supervisor will arrange for all the tasks 
belonging to it to be terminated as well. Task are initially given the priority as passed in CL, but the 
priority may be changed at any time with the procSetPriority service. A task cannot have any heap 
space since the parent process owns and controls the heap. Thus the parent must provide any space that 
the task requires. 


No services which use the heap allocator can be called. Thus a task cannot open an I/O channel; the 
parent must open the channel on behalf of the task. 


A good way to co-ordinate a task and its parent is to use a semaphore to lock the shared data. The 
semaphore is created with a value of one. Before either parent or task accesses the data, the semaphore is 
waited on with semwait. When the data is no longer required the semaphore is signalled with 
SemSignalOnce. 


ProcResume Resume a process 


BX The process handle. 
RETURN: Carry clear 


Success. 
RETURN: = Carry set 
ArgumentErr The process is not currently suspended. 
NotExistErr The process does not exist. 
PANIC: 
PanicProcl Invalid process ID. 


Resume a suspended process specified in BX. 


ProcSuspend Suspend a process 


BX The process handle. 
RETURN: Carry clear 


Success. 
RETURN: Carry set 

NotExistsErr The process does not exist. 

FailErr Tried to suspend the null, supervisor or file server process. 
PANIC: 

PanicProcl Invalid process ID. 


Suspend the process specified in BX. 


Processes which are on the ready queue or currently running (i.e. the calling process), will be suspended 
immediately. 


Attempting to suspend a process which is currently waiting on the semaphore or delta queues will cause 
that process to be marked as requiring suspension. When it is eventually transferred to the ready queue, it 
will be suspended immediately. 


10-5 


EPOC O/S SYSTEM SERVICES 


Conversely, attempting to resume a process which is currently waiting on the semaphore or delta queues 
and is marked as requiring suspension, will simply be unmarked. 


It is not possible to suspend the null, supervisor or file server process. 


A suspended process is resumed by calling the procResume Service. 


Prockill Kill a process 
AL The kill reason. 
BX The process handle. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 

NotExistsErr The process does not exist. 

FailErr Tried to kill the null, supervisor or file server process. 
PANIC: 

PanicProcl Invalid process ID. 


Kill the process specified in BX. 


Regardless of what state the process is in, it will be killed and the kill reason will be remembered as the 
reason for death. It is recommended that the procTerminate service is called in preference to this service 
as the terminate service will allow any processes which have cleanup code to execute this code, whereas 
this service will just kill the process immediately. 


ProcOnTerminate Register termination 
BX The message to be sent when being terminated. 

RETURN: None 

PANIC: 
PanicMess2 Messaging not initialised. 


Register a message to be sent when termination of the process is requested with procTerminate. 


Messaging must previously have been initialised with the MessInit service. Having registered an "on 
termination" message, it can be cancelled later by registering the message 0. A process which registers an 
"on termination" message is duty bound to respond to the message by eventually committing suicide by 
calling the prockill service. 


ProcTerminate Terminate a process 
AL The terminate reason. 
BX The process handle. 


RETURN: Carry clear 


Success. 
RETURN: = Carry set 

NotExistsErr The process does not exist. 

FailErr Tried to terminate the null, supervisor or file server process. 
PANIC: 

PanicProcl Invalid process ID. 


Terminate the process specified in BX. 


If the process has registered an "on terminate" message then it will be sent this message. If it has no "on 
terminate" message registered then it will be killed. This is the recommended way to terminate processes. 


10 - 6 


10 PROCESS MANAGEMENT 


ProcPanicByld Panic a process 
AL The panic reason. 
BX The process handle. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 

NotExistsErr The process does not exist. 

FailErr Tried to panic the null, supervisor or file server process. 
PANIC: 

PanicProcl Invalid process ID. 


Panic the process specified in BX. 


Regardless of what state the process is in, it will be killed and the panic reason will be remembered. 


ProcNameByld Get a process name by ID 
BX The process handle. 
ES:DI Pointer to the buffer to receive the name. 


RETURN: Carry clear 


Success. 
RETURN: = Carry set 

NotExistsErr The process does not exist. 
PANIC: 

PanicProcl Invalid process ID. 


Returns the name of the process specified by the ID in BX. The buffer should be large enough for 
MaxNameESize bytes. 


ProcRename Rename a process 
BX The ID of the process to be renamed. 
ES:DI Pointer to the new name for the process. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
NotExitsErr The process does not exist. 
NameErr The new name was invalid. 
FailErr Tried to rename the null, supervisor or file server process. 


PANIC: None 


Rename the process whose ID is contained in BX to the new name pointed to by ES:DI. The new name 
can be between | and 8 characters long and must be zero terminated. No check is made to ensure that the 
new name is unique. 


ProcFind Find all processes 
BX The find handle. 
ES:DI Pointer to a wild card match string. 
DS:SI Pointer to the buffer to receive the name of the found process. 


10-7 


EPOC O/S SYSTEM SERVICES 


RETURN: Carry clear 


AX The find handle for the next find. 
RETURN: Carry set 

NotExistsErr No more processes found. 
PANIC: 

PanicProcl Invalid process ID. 


Finds all the processes which match the wild card string pointed to by DI. 
The first time this service is called, BX should be set to zero; the first process will be found. 


After a find, this service returns the find handle in the AX register. The find handle must be supplied on 
the next call to this service to find the next process. No memory is used by this service and it can be 
abandoned at any time without taking any further action. The wild card string must always be supplied in 
DI and should remain the same between calls to this service. The buffer to receive the name must be at 
least MaxNameESize+2 bytes long. 


ProcWatchaAllExits Watch all exits 


BX The message number. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

FailErr Watch all exits already activated. 
PANIC: None 


A process can arrange to be sent the message specified in BX whenever a process exits. Only one process 
at a time can request this service and it is usually reserved for the SHELL so that it can monitor the exits 
of all processes. Messaging must be initialised before this service can be invoked. Requesting a message 
number 0 cancels this service. The body of the message, when it arrives, contains two words; the first 
word is the ID of the exiting process and the second is the reason for the exit. 


e ProcPanic Panic the current process 


AL The panic reason. 
RETURN: None 
PANIC: None 


Panic the current process for the reason specified in AL. This is suicide of some kind. 


e ProcCopyFromByld Copy data from a process by ID 


BX The process handle. 

x The number of bytes to be copied. 

ES:DI Pointer to the destination buffer in the current process. 

SI The offset in the process, specified in BX, data segment from which 


the data is to be copied. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
ArgumentErr Process did not exist or SI+CX exceeded the segment size. 
PANIC: None 


Copies CX bytes of data from the buffer pointed to by SI within the data segment of the process specified 
by BX to the buffer pointed to by DI. If CX is less than or equal to 64 then the data will be copied with 
interrupts disabled. 


10-8 


10 PROCESS MANAGEMENT 


e ProcindStringCopyFromByld Copy strings from process by ID 


BX The process handle. 

CX The maximum number of bytes to be copied. 

ES:DI Pointer to the destination buffer in the current process. 

SI The address of a pointer to a string in the processes (specified in 


BX) data segment from which the string is to be copied. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
ArgumentErr Process did not exist or SI+CX exceeded the segment size. 
PANIC: None 


Copies up to CX bytes of text to the buffer pointed to by DI; the source of the text string is in the data 
segment of the process specified by BX and SI points to the pointer of the text string. If CX is less than or 
equal to 64 then the data will be copied with interrupts disabled. 


e ProcCopyToByld Copy data to a process by ID 


BX The process handle. 
cx The number of bytes to be copied. 
DI The offset in the process, specified in BX, data segment to which 


the data is to be copied. 


DS:SI Pointer to the source buffer in the current process from which the 
data is to be copied. 


RETURN: Carry clear 

Success 
RETURN: Carry set 

ArgumentErr Process did not exist or DI+CX exceeded the segment size. 
PANIC: None 


Copies CX bytes of data from the buffer pointed to by SI to the buffer pointed to by DI in the data segment 
of the process specified by BX. If CX is less than or equal to 64 then the data will be copied with 
interrupts disabled. 


10-9 


CHAPTER 11 


DATE AND TIME MANAGEMENT 


Absolute and relative times 


The operating system has the concept of relative and absolute times and all services work in either relative 
or absolute time. 


Absolute time services always work in seconds where the seconds are in the same format as the system 
time, i.e. they specify a real time in the future. If the operating system enters standby mode with an 
absolute time event still pending then it will ensure that it will wake up in time to service the event. Thus, 
if a process gets the system time, adds 24*60*60 to it and then waits absolutely until that time then the 
operating system will ensure that it is running 24 hours later. Absolute times are unaffected by changing 
the system time so that if the system time is advanced by | day then absolute times are not also advanced 
by 1 day. 


Relative time services work in tenths of a second or system ticks. Unlike absolute times, a relative time 
means x units from now. Again, changing the system time will have no effect upon relative times. If a 
relative time is set for 5 seconds and the system time is advanced by 1 hour, the relative time will still wait 
for 5 seconds. Again, unlike absolute times, if the operating system enters standby mode, the time in 
standby is not taken into account. If there is a relative time outstanding and the operating system enters 
standby mode for 1 hour then the relative time will be 1 hour plus 5 seconds. This also means that the 
operating system will not exit from standby mode to service relative time events. 


TimWaitAbsolute Wait to a given time 


CX:DX The time to wait till in seconds. 
RETURN: = Carry clear 
Success 
RETURN: Carry set 
ArgumentErr The value in CX:DX was in the past. 
PANIC: None 
Sleep the process calling this service until the system time given in CX:DX, where CX:DxX is a 32 bit 


integer. 


DX is the least significant word and CX is the most significant word. This is an absolute time service. 


11-1 


EPOC O/S SYSTEM SERVICES 


TimSleepForTenths Sleep for tenths of a second 


CX:DX The time to sleep in tenths of a second. 
RETURN: Carry clear 


Success 
RETURN: = Carry set 
ArgumentErr The value in CX:DX was negative. 
OverflowErr The value in CX:DX overflowed when converted to ticks. 


PANIC: None 
Sleep the process calling this service for CX:DX tenths of a second, where CX:DX is a 32 bit integer. 


DX is the least significant word and CX is the most significant word. If sleep is requested for N tenths, 
then the sleep is guaranteed to be between N and N+1 tenths. 


This is a relative time service. 


TimSleepForTicks Sleep for system clock ticks 


CX:DX The time to sleep in system clock ticks. 
RETURN: Carry clear 
Success 
RETURN: = Carry set 
ArgumentErr The value in CX:DX was negative. 
PANIC: None 
Sleep the process calling this service for CX:DX system clock ticks where CX:DX is a 32 bit integer. 


DX is the least significant word and CX is the most significant word. If sleep is requested for N tenths, 
then the sleep is guaranteed to be between N and N+1 ticks. 


On IBM compatible PCs, a clock tick occurs 18.2 times a second and on the SIBO hardware occurs 32 
times a second. 


A request to sleep for zero ticks is valid and will just force a re-schedule; the process calling this service 
loses the remainder of its time slice if there are other processes at the same priority. 


This is a relative time service. 


TimGetSystemTime Get the system time 


None 
RETURN: 

AX: BX System time in seconds. 
PANIC: None 


Returns the system time in seconds. 


The system time is stored as a 32 bit unsigned integer; the number of seconds since Ist. January 1970 at 
00:00:00 (i.e. UNIX time). BX is the least significant word and AX is the most significant word. 


TimSetSystemTime Set the system time 


CX:DX The new system time. 
RETURN: None 
PANIC: None 


Sets the system time to the new value passed in CX:DX. 


The system time is stored as a 32 bit unsigned integer; the number of seconds since Ist. January 1970 at 
00:00:00 (i.e. UNIX time). DX is the least significant word and CX is the most significant word. 


11-2 


11 DATE AND TIME MANAGEMENT 


TimSystemTimeToDaySeconds Convert sys’ time to day secs 
CX:DX The time to be converted in seconds. 
DS:DI Pointer to a DyScEnt Structure. 


RETURN: None 
PANIC: None 


Converts the system time to the number of days since 1970 and the number of remaining seconds. 


DS:DI points to a pyscEnt structure which contains a long integer number of days and a long integer 
number of seconds. DX is the least significant word and CX is the most significant word of the time to be 
converted. 


TimDaySecondsToSystemTime Convert day secs to system time 


DS:SI Pointer to a DyScEnt structure. 
RETURN: Carry clear 
AX: BX System time. 
RETURN: Carry set 
ArgumentErr DyScSeconds greater than 24*60*60 
OverflowErr Exceeded system time. 


PANIC: None 


Convert a DyScEnt structure pointed to by DS:SI to system time. 


BX is the least significant word and AX is the most significant word of the system time. 


TimDaySecondsToDate Convert day seconds to date 
DS:SI Pointer to a DyScEnt structure. 
DS:DI Pointer to a DateEnt structure. 


RETURN: Carry clear 


Success 

RETURN: Carry set 
ArgumentErr DyScSeconds greater than 24*60*60 
OverflowErr Years out of range. 


PANIC: None 


Converts the day seconds in the pyscEnt structure pointed to by DS:SI to date in the pateEnt structure 
pointed to by DS:DI. 


TimDateToDaySeconds Convert date to day seconds 
DS:SI Pointer to a DateEnt structure. 
DS:DI Pointer to a DyScEnt Structure. 


RETURN: Carry clear 

Success 
RETURN: = Carry set 

ArgumentErr Date is invalid. 
PANIC: None 


Converts the date in the pateEnt structure pointed to by DS:SI to day seconds in the pyscEnt structure 
pointed to by DS:DI. 


EPOC O/S SYSTEM SERVICES 


TimDaysInMonth Number of days in a month 
CH The month number, 0 to 11 (0 equals January). 
CL The year number (0 equals 1900). 
RETURN: Carry clear 
AX Number of days in the month. 
RETURN: Carry set 
ArgumentErr Invalid month. 


PANIC: None 


Returns the number of days in a month corresponding to the month number passed in CH and the year 
number passed in CL. 


The value in AX will be in the range 28 to 31. If this service returns 29 for any year in CL and | in CH 
then the year is a leap year (i.e. February with 29 days). 


TimDayOfWeek Week day number 


CX:DX The number of days since 1900. 
RETURN: 
AX The week day number, 0 = Monday. 


PANIC: None 
Returns the weekday number corresponding to the number of days since 1900 in CX:DX. 


DX is the least significant word and CX is the most significant word. The value in AX will be in the 
range 0 to 6, with 0 being Monday and 6 being Sunday. 


TimNameOfDay Name of day 


AL The day of week number, 0 to 6. 

DS:BX Pointer to a buffer to receive the name of the day. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

ArgumentErr The day of week number is not in the range 0 to 6. 
PANIC: None 
Returns the name of the day corresponding to the day of week number in AL. 


The day name is returned as a zero terminated string in the buffer pointed to by DS:BX. The maximum 
size of the string is 32 bytes. This is a language dependent service. 


TimNameOfMonth Name of month 
AL The month number, 0 to 11. 
DS:BX Pointer to a buffer to receive the name of the month. 


RETURN: Carry clear 

Success 
RETURN: = Carry set 

ArgumentErr The month number is not in the range 0 to 11. 
PANIC: None 


Returns the name of the month corresponding to the month number in AL. 


The month name is returned as a zero terminated string in the buffer pointed to by DS:BX. The maximum 
size of the string is 32 bytes. This is a language dependent service. 


11-4 


11 DATE AND TIME MANAGEMENT 


TimWeekNumber Week number 
CX:DX The number of days since Jan 1 1900. 

RETURN: Carry clear 
AX The week number in the range 1-53. 

RETURN: Carry set 
ArgumentErr The number of days exceeds the year 2165. 


PANIC: None 


Returns the week number corresponding to the number of days since Jan 1 1900. 


This service takes the value in cbataStartofweek in the country dependent data into account. 


¢ TimNameOfDayAbb Abbreviated name of day 


AL The day of week number, 0 to 6. 

BX Pointer to a buffer to receive the name of the day. 
RETURN: Carry clear 

Success 
RETURN: Carry set 

ArgumentErr The day of week number is not in the range 0 to 6. 
PANIC: None 
Returns the abbreviated name of the day corresponding to the day of week number in AL. 


The day name is returned as a zero terminated string in the buffer pointed to by BX. This is a language 
dependent service. 


All month name abbreviations for a particular language have the same length and could be one, two or 
three characters. The abbreviation will not exceed three characters in any language. 


¢ TimNameOfMonthAbb Abbreviated name of month 
AL The month number, 0 to 11. 
BX Pointer to a buffer to receive the name of the month. 


RETURN: Carry clear 

Success 
RETURN: = Carry set 

ArgumentErr The month number is not in the range 0 to 11. 
PANIC: None 


Returns the abbreviation for the name of the month corresponding to the month number in AL. 


The month name is returned as a zero terminated string in the buffer pointed to by BX. This is a language 
dependent service. 


All month name abbreviations for a particular language have the same length and could be one, two or 
three characters. The abbreviation will not exceed three characters in any language. 


11-5 


CHAPTER 12 


CONVERSION MANAGEMENT 


ConvUnsignedintToBuffer Unsigned integer to buffer 
BX The number to be converted. 
cx The conversion radix. 
ES:DI Pointer to buffer to receive the converted number. 
RETURN: 
AX The number of characters written to DI. 


PANIC: None 


Converts an unsigned integer in BX to its corresponding digits in the buffer pointed to by DI using the 
radix specified in CX, i.e. 2 for binary, 8 for octal, 10 for decimal and 16 for hexadecimal. 


The number of characters written to the buffer at DI is returned in AX. 


ConvUnsignedLongIntToBuffer Unsigned long integer to buffer 


DX:BX The number to be converted. 

fone The conversion radix. 

ES:DI Pointer to buffer to receive the converted number. 
RETURN: 

AX The number of characters written to ES:DI. 


PANIC: None 


Converts an unsigned long integer in DX:BX to its corresponding digits in the buffer pointed to by DI 
using the radix specified in CX, i.e. 2 for binary, 8 for octal, 10 for decimal and 16 for hexadecimal. 


BX is the least significant word and DX is the most significant word. The number of characters written to 
the buffer at DI is returned in AX. 


ConvintToBuffer Integer to buffer 
BX The number to be converted. 
ES:DI Pointer to buffer to receive the converted number. 

RETURN: 
AX The number of characters written to DI. 


PANIC: None 
Converts an integer in BX to its corresponding digits in the buffer pointed to by DI. 


If BX is negative then the first character in the buffer will be a minus sign '-'. The conversion is performed 
using a radix of 10. The number of characters written to the buffer at DI is returned in AX. 


12-1 


EPOC O/S SYSTEM SERVICES 


ConvLongIntToBuffer Long integer to buffer 
DX:BX The number to be converted. 
ES:DI Pointer to buffer to receive the converted number. 

RETURN: 
AX The number of characters written to DI. 


PANIC: None 
Converts a long integer in DX:BX to its corresponding digits in the buffer pointed to by DI. 
If BX is negative then the first character in the buffer will be a minus sign '-'. The conversion is performed 


using a radix of 10. BX is the least significant word and DX is the most significant word. The number of 
characters written to the buffer at DI is returned in AX. 


ConvArgumentsToBuffer Convert arguments to buffer 
SS:BX Pointer to the argument list. 
ES:DI Pointer to buffer to receive the converted arguments. 
DS:SI Pointer to format control string. 
RETURN: 
AX The number of characters written to ES:DI. 


PANIC: None 
Converts the values in the list pointed to by BX into a buffer at DI. 
The conversion is controlled by the format string pointed to by SI. This service is used by p_atob()in 


PLIB. Note that the arguments in the list pointed to BX must be as if they were being passed on the stack 
to a C function. i.e. only words and double words are allowed. 


ConvStringToUnsignedint String to unsigned integer 
cx Radix for conversion. 
DS:SI Pointer to zero terminated string to be converted. 
RETURN: Carry clear 
AX Resultant unsigned integer. 
SI Pointer to the first unused character in the string. 
RETURN: Carry set 
FailErr No valid digits in string. 
OverflowErr Number too large for an unsigned integer. 


PANIC: None 


Convert a zero terminated string to an unsigned integer using the radix specified in CX, i.e. 2 for binary, 
8 for octal, 10 for decimal and 16 for hexadecimal. The conversion will stop at a character that is not valid 
for the conversion radix. 


If the string consists only of valid digits and the number does not overflow then SI will be returned 
pointing to the terminating 0 otherwise SI will be pointing at the invalid digit. 


ConvStringToUnsignedLongint String to unsigned long integer 


cx Radix for conversion. 

DS:SI Pointer to zero terminated string to be converted. 
RETURN: Carry clear 

AX:BX Resultant unsigned long integer. 

SI Pointer to the first unused character in the string. 


12-2 


12 CONVERSION MANAGEMENT 


RETURN: = Carry set 

FailErr No valid digits in string. 

OverflowErr Number too large for an unsigned long integer. 
PANIC: None 


Convert a zero terminated string to an unsigned long integer using the radix specified in CX, i.e. 2 for 
binary, 8 for octal, 10 for decimal and 16 for hexadecimal. The conversion will stop at a character that is 
not valid for the conversion radix. 


If the string consists only of valid digits and the number does not overflow then SI will be returned 
pointing to the terminating 0 otherwise SI will be pointing at the invalid digit. The result is returned in 
BX:AX where BX is the least significant word and AX is the most significant word. 


ConvStringTolnt String to integer 
DS:SI Pointer to zero terminated string to be converted. 
RETURN: Carry clear 
AX Resultant integer. 
SI Pointer to the first unused character in the string. 
RETURN: Carry set 
FailErr No valid digits in string. 
OverflowErr Number too large for an integer. 


PANIC: None 


Convert a zero terminated string to an integer using a radix of 10. 


The string can begin with a minus character '-', in which case the integer will be negative or a plus 
character '+', in which case the integer will be positive. The maximum positive value is 32767 and the 
maximum negative value is -32768. The conversion will stop at a character that is invalid for a conversion 
radix of 10. 


If the string consists only of valid digits and the number does not overflow then SI will be returned 
pointing to the terminating 0 otherwise SI will point to the invalid digit. 


ConvStringToLongint String to long integer 
DS:SI Pointer to zero terminated string to be converted. 
RETURN: Carry clear 
AX:BX Resultant long integer. 
SI Pointer to the first unused character in the string. 
RETURN: Carry set 
FailErr No valid digits in string. 
OverflowErr Number too large for a long integer. 


PANIC: None 


Convert a zero terminated string to a long integer using a radix of 10. 


The string can begin with a minus character '-', in which case the long integer will be negative or a plus 
character '+', in which case the long integer will be positive. The maximum positive value is 4294967295 
and the maximum negative value is -4294967295. The conversion will stop at a character that is invalid 
for a conversion radix of 10. 


If the string consists only of valid digits and the number does not overflow then SI will be returned 
pointing to the terminating 0 otherwise SI will point to the invalid digit. The result is returned in BX:AX 
where BX is the least significant word and AX is the most significant word. 


12-3 


EPOC O/S SYSTEM SERVICES 


ConvFloatToBuffer Floating point number to buffer 
SI Pointer to the float to be converted. 
DX Pointer to the format structure. 
DI Pointer to buffer to receive the converted float. 
RETURN: Carry clear 
AX Length of converted string. 
RETURN: Carry set 
ArgumentErr Invalid float, or illegal [DX].ptobType. 
FailErr Representation exceeds [DX].pt obwidth characters. 
OverflowErr Float >>= 1E+100. 
UnderflowErr Float << 1E-99. 


PANIC: None 


Converts a double floating point number in [SI] to a printable ASCII zero terminated string pointed to by 
DI using the supplied format specification. The format specification is contained in the ptobEnt structure 
as defined in epocdefs.inc as: 


Dtob struc ; dtob format string structure 
DtobType db ?  j conversion type 
DtobWidth db 
DtobNdec db 
DtobPoint db 
DtobTriad db 
DtobTrilen db ; threshold for triad character use 
DtobEnt ends 


; width of representation in characters 
; number of decimal places 

; decimal point character 

; triad separator character 


VN VV Vy 


Numbers may be represented in various formats by setting ptobType as follows:- 
@ DtobTypeFixed, fixed point format. 
@ DtobTypeExponent, exponent format. 
@ DtobTypeGeneral, general format. 


Integer format is obtained as a special case of fixed point format where the number of decimal places 
required is zero. The parameter [DX].pt obwidth specifies the maximum number of characters allowed to 
represent the number and there should be [DX].pt obwidth+1 bytes (the +1 is for the zero terminator) 
reserved at DI. If the output exceeds this limit, railzrr is returned. Although numbers are normally 
displayed right-aligned, convFloat ToBuffer makes no attempt to align the result in the buffer. Alignment 
is quite different for monospaced and proportionally spaced character fonts and is best handled by post- 
processing the output from convFloatToBuffer. 


[DX].pt obwidth should be in the range | to 255 inclusive. The parameter [DX].ptobNdec specifies the 
number of decimal digits following the decimal point when [DX].pDtobType 1S DtobTypeFixed OF 
DtobTypeExponent. [DX].ptobNdec must be in the range 0 to FloatSignificantDigits (15 for IEEE 
floating point format) inclusive. The parameter [DX].ptobPoint specifies the decimal point character 
which separates the integer portion from the fractional portion and would normally be either a'.' or a',’ . 


The parameter [DX].pt obTriad specifies the triad separator character which delimits groups of 3 digits in 
the integer part of the fixed point representation and would normally be either ',’ or '.' or '' . The 
insertion of triad separation characters is disabled if [DX].ptobTrilen is 0 and otherwise enabled when 
the integer portion of the number contains greater than [DX].ptobTrilen digits. Normally one would use 
[DX].ptobTrilen=1 to enable triad separation and [DX].ptobTrilen is 4 to conform to French 


conventions for triad separator insertion. 


In all cases, negative numbers are represented by the insertion of a leading '-' sign (positive numbers do 
not have a leading '+' sign). This can easily be post-processed to obtain a bracketed representation of 
negative numbers, if desired. There can never be more than FloatSignificantDigits(15 FOR IEEE 
floating point format). Where there are less than FloatSignificantDigits, the number is rounded to the 
number of significant digits displayed. 


12-4 


12 CONVERSION MANAGEMENT 


The limitation to floats with magnitude between 1E-99 and 1E+100 results from the use of lookup tables 
for speedily generating the results. Floating point numbers of magnitude smaller than 1E-99 can easily be 
converted to 0 before calling this service. The detailed formatting details as a function of [DX].ptobtType 
is as follows: 


@ DtobTypeFixed - The number is represented with [DX].pt obNdec decimal places where 
[DX].pt obNdec may be zero to represent an integer (in which case no decimal point character is 
displayed). If the ASCII form exceeds [DX].pt opbwidth (usually due to the number being large 
and having too many digits before the decimal point), railzrr is returned. A zero is displayed in 
the form "0.000" where there are [DX].pt obNdec zeros following the decimal point or as just "0" 
if [DX].DtobNdec is zero. 


@ DtobTypeExponent - The number is represented in exponent notation with one non-zero digit 
before the decimal point and [DX].pt obNdec digits beyond the decimal point followed by 'E', a 
sign ('+' or '-') and the exponent as two digits (with leading zero if necessary). If [DX].ptobNdec 
is zero, the number is rounded to one digit of precision and no decimal point is displayed. A zero 
is displayed in the form "0.000E+00" where there are [DX].pt obNdec zeros following the decimal 
point or as "OE+00" if [DX].ptobNdec is zero. Triad separation is not available and triad 
separation parameters are ignored. 


@ DtobTypeGeneral - converts either as fixed format (with no triad separator) or exponent format, 
making best use of [DX].ptobwidth. Here, "making best use" is defined as showing the greater 
number of significant digits and preferring fixed format when the number of significant digits 
shown is the same. The number of decimal places is chosen as a function of [DX].ptobwidth and 
the value of [DX].pt obNdec is ignored. A zero is displayed as just "0". Triad separation is not 
available and triad separation parameters are ignored. 


ConvStringToFloat String to float 


SI address of pointer to text to convert 
Dx Decimal point character 
DI Pointer to double destination 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
FailErr Failed to recognise a number. 
OverflowErr Number too large. 
UnderflowErr Number less than 1E-99, 0 written to [DI]. 


PANIC: None 


Scans the string for a number and writes the value as a double float to [DI]. If underflow occurs, zero is 
written to [DI]. 


The supplied ASCTI string should take the form: 
[+|-]<<int>.<fract>[E|e] [+|-]<<exp>> 
Where: 


e = The leading '+' sign may be omitted for positive numbers. <<int>> and <<fract>> are optional 
but at least one should be present. 


e Leading zeros in <int> are legal but have no effect. 
e = Trailing zeros in <fract> are legal but have no effect. 


e = There is no reasonable limit to the number of significant digits but digits which are beyond the 
precision of the floating point representation will not be reflected in the mantissa of the number 
which is produced. 


e The exponent field which starts with and 'E' or 'e' is optional. 
e = The leading '+' sign in the exponent field may be omitted for positive exponents. 


e The resulting number should be in the range approximately 1e-99 to approximately 1e+99. 


12-5 


CHAPTER 13 


LONG INTEGER MANAGEMENT 


e LongintCompare Compare two long integers 
AX: BX The left operand long integer. 
CX:DX The right operand long integer. 
RETURN: 
Flags < 0 If AX:BX < CX:DX 
Flags = 0 If AX:BX = CX:DX 
Flags >> 0 If AX:BX > CX:DX 


PANIC: None 


Compares two long integers for equality. The flags are set in the same way as for a normal compare for 
integers, i.e. CMP AX:BX, CX:DX. 


Note that the flags are set so that only the signed tests can be performed, i.e. JLE,JL,JE,JNE,JG,JGE and 
not the unsigned tests JB,JBE,JA,JAE. 


All registers are preserved by this service. 


e LongintMultiply Long integer multiplication 
AX:BX The left operand long integer. 
CX:DX The right operand long integer. 
RETURN: = Carry clear 
AX:BX Product. 
RETURN: Carry set 
OverflowErr AX:BX * CX:DX is bigger than 32 bits. 


PANIC: None 


Multiply two long integers together. If the resultant product overflows then an error will be returned by 
setting the carry flag. 


If no error occurs, the flags will not be set for the result; carry will be clear. 


e LongintDivide Long integer division 
AX: BX The left operand long integer (dividend). 
CX:DX The right operand long integer (divisor). 
RETURN: = Carry clear 
AX: BX The quotient. 
CX:DX The remainder. 
RETURN: Carry set 
DivideByZeroErr CX:DX is zero. 


PANIC: None 


13-1 


EPOC O/S SYSTEM SERVICES 


Divide one long integer by another. 
If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. 
If no error occurs, the flags will not be set for the result; carry will be clear. 


The remainder will have the same sign as the dividend. 


e LongUnsignedintCompare Compare 2 unsigned long integers 


AX:BX The left operand unsigned long integer. 

CX:DX The right operand unsigned long integer. 
RETURN: 

Flags << 0 If AX:BX < CX:DX 

Flags = 0 If AX:BX = CX:DX 

Flags > 0 If AX:BX > CX:DX 


PANIC: None 


Compares two unsigned long integers for equality. 
The flags are set in the same way as for a normal compare for integers, i.e. CMP AX:BX, CX:DX. 


Note that the flags are set so that only the unsigned tests can be performed, i.e. JBE,JB,JE,JNE,JA,JAE 
and not the signed tests JL,JLE,JG,JGE. 


All registers are preserved by this service. 


e LongUnsignedintMultiply Unsigned long integer multiplication 


AX:BX The left operand unsigned long integer. 
CX:DX The right operand unsigned long integer. 
RETURN: Carry clear 
AX:BX Product. 
RETURN: Carry set 
OverflowErr AX:BX * CX:DX is bigger than 32 bits. 


PANIC: None 
Multiply two unsigned long integers together. 


If the resultant product overflows, an error will be returned by setting the carry flag. 


If no error occurs, the flags will not be set for the result; carry will be clear. 


e LongUnsignedIntDivide Unsigned long integer division 
AX:BX The left operand unsigned long integer (dividend). 
CX:DX The right operand unsigned long integer (divisor). 
RETURN: Carry clear 
AX: BX The quotient. 
CX:DX The remainder. 
RETURN: Carry set 
DivideByZeroErr CX:DX is zero. 


PANIC: None 


Divide one unsigned long integer by another. 
If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. 


If no error occurs, the flags will not be set for the result; carry will be clear. 


13-2 


13 LONG INTEGER MANAGEMENT 


LongUnsignedintRandom Unsigned long integer random number 


DS:BX Pointer to the unsigned long integer seed. 
RETURN: 
AX: BX The unsigned long integer random number. 


PANIC: None 
Return an unsigned long integer random number given the seed. 
The 4 bytes pointed to by BX are used to generate the next random number which is returned in AX:BX 


as well as being written back to the seed. The seed can start with any number required from which the 
same sequence of random numbers will be generated. 


CHAPTER 14 


FLOATING POINT NUMBER HANDLING 


e FloatCompare Compare two Floats 
DI Pointer to left hand floating point operand. 
SI Pointer to right hand floating point operand. 
RETURN: 
Z flag set if [DIJ=[S]]. 
S flag set if [DI]<<[S]]. 


PANIC: None 


Compares the two floating point operands pointed to by SI and DI, setting the Z and the S flags as for 
[DI]-[SI]. The Z flag is set if the operands are equal and the S flag is set if [DI] is less than [SI]. 


¢ FloatMultiply Multiply two floats 
DI Pointer to left hand (and destination) floating point operand. 
Si Pointer to right hand floating point operand. 
RETURN: = Carry clear 
[DI] 
RETURN: Carry set 
OverFlowError Product exponent overflowed. 


PANIC: None 
Multiplies the two floating point operands pointed to by SI and DI. Returns the product in [DI]. 


« FloatDivide Divide floats 
DI Pointer to left hand (and destination) floating point operand. 
SI Pointer to right hand floating point operand. 
RETURN: = Carry clear 
[DI] 
RETURN: Carry set 
OverFlowError Quotient exponent overflowed. 


PANIC: None 
Divides the operand at DI by the operand at SI and returns the quotient in [DI]. 


14-1 


EPOC O/S SYSTEM SERVICES 


e FloatAdd Add two Floats 


DI Pointer to left hand (and destination) floating point operand. 
SI Pointer to right hand floating point operand. 
RETURN: Carry clear 
[DI] 
RETURN: Carry set 
OverFlowError Sum exponent overflowed. 


PANIC: None 
Adds the two floating point operands pointed to by SI and DI. Returns the sum in [DI]. 


¢ FloatSubtract Subtract Floats 
DI Pointer to left hand (and destination) floating point operand. 
SI Pointer to right hand floating point operand. 
RETURN: Carry clear 
[DI] 
RETURN: = Carry set 
OverFlowError Sum exponent overflowed. 


PANIC: None 
Subtracts the operand at SI from the operand at DI and returns the difference in [DI]. 


e FloatNegate Negate a Floats 


DI Pointer to floating point operand. 
RETURN: 

[DI] 
PANIC: None 
Negates the float at DI. 


¢ FloatToLong Convert Float to a signed long 
SI Pointer to float operand to be converted. 

RETURN: Carry clear 
AX:BX Long integer result. 

RETURN: Carry set 
ArgumentErr Float not in range [-2**31,2**31-1]. 


PANIC: None 


Converts the floating point operand pointed to by SI to a 32 bit signed long integer in AX:BX with the 
most significant word in AX. 


¢ FloatTtoUnsignedLong Convert Float to unsigned long 
SI Pointer to float operand to be converted. 

RETURN: Carry clear 
AX: BX Unsigned long integer result. 

RETURN: Carry set 
ArgumentErr Float not in range [-2*32+1,2**32-1]. 


PANIC: None 


Converts the floating point operand pointed to by SI to a 32 bit unsigned integer in AX:BX with the most 
significant word in AX. Note that the sign of the float is ignored. 


14-2 


14. FLOATING POINT NUMBER HANDLING 


¢ FloatTolnt Convert Float to a signed integer 
SI Pointer to float operand to be converted. 

RETURN: Carry clear 
AX unsigned integer result. 

RETURN: Carry set 
ArgumentErr Float not in range [-32768,32767]. 


PANIC: None 
Converts the floating point operand pointed to by SI to a 16 bit signed integer in AX. 


¢ FloatToUnsignedint Convert Float to unsigned integer 
SI Pointer to float operand to be converted. 

RETURN: Carry clear 
AX Integer result. 

RETURN: Carry set 
ArgumentErr Float not in range [-65535,65535] 


PANIC: None 


Converts the floating point operand pointed to by SI to a 16 bit unsigned integer in AX. The sign of the 
float is ignored. 


¢ LongToFloat Convert signed long to Float 
AX:BX Signed long to be converted. 
DI Pointer to destination float. 

RETURN: 
[DI] 


PANIC: None 
Converts the signed 32 bit integer in AX:BX to a float at DI. 


¢ IntToFloat Convert signed integer to Float 
AX Signed integer to be converted. 
DI Pointer to destination float. 

RETURN: 
[DI] 


PANIC: None 
Converts the signed 16 bit integer in AX to a float at DI. 


¢ UnsignedIintToFloat Convert unsigned integer to Float 
AX Unsigned integer to be converted. 
DI Pointer to destination float. 

RETURN: 
[DI] 


PANIC: None 
Converts the unsigned 16 bit integer in AX to a float at DI. 


CHAPTER 15 


FLOATING POINT FUNCTION INTERFACE 


FloatASin Arcsine of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float. 


PANIC: None 


Calculates the Arcsine in radians of a double argument in [SI] returning the result in [DI]. [SI] is 
preserved unless SI equals DI. 


FloatATan Arctangent of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: = Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float. 


PANIC: None 


Calculates the Arctangent in radians of a double argument in [SI] returning the result in [DI]. [SI] is 
preserved unless SI equals DI. 


FloatCos Cosine of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: = Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float, or argument not in range. 


PANIC: None 


Calculates the Cosine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved 
unless SI equals DI. 


15-1 


EPOC O/S SYSTEM SERVICES 


FloatExp Exponentiation of a float 


DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float. 
PANIC: None 


Calculates the exponentiation of a double argument in [SI] returning the result in [DI]. [SI] is preserved 
unless SI equals DI. 


Floatint Zero fractional part of a Float 


DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float. 
PANIC: None 


Removes the fractional part of the float in [SI] and returns the result as a float in [DI]. [SI] is preserved 
unless SI equals DI. 


FloatLn Natural logarithm of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float, or argument not greater than zero. 


PANIC: None 


Calculates the Natural Logarithm of a double argument in [SI] returning the result in [DI]. [ST] is 
preserved unless SI equals DI. 


FloatLog Logarithm of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float, or argument not greater than zero. 


PANIC: None 


Calculates the Logarithm of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless 
ST equals DI. 


15 -2 


15 FLOATING POINT FUNCTION INTERFACE 


FloatMod Modulo of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
Dx Pointer to floating point modulo value. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float. 
OverflowErr Integer overflow. 


PANIC: None 


Calculates [SI] modulo [DX] returning the result in [DI]. The calculation is [DI] = [ST] - 
FloatInt({[S1]/[DX])*[DX]. [SI] and [DX] is preserved unless SI or DX equals DI. 


FloatPow Power of two Floats 
DI Pointer to destination floating point operand. 
SI Pointer to floating point base. 
Dx Pointer to floating point power. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float, 040, or [SI]<<0O with [DI] not integral. 
OverflowErr Integer overflow. 


PANIC: None 


Calculates [SI] raised to the power of [DI] returning the result in [DI]. [SI] and [DX] are preserved unless 
SI or DI equals DI. 


FloatRand Float random number 


DI Pointer to destination floating point number. 
SI Pointer to unsigned long integer seed. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
None 
PANIC: None 


Generates a pseudo random number using the unsigned long integer seed in [SI] and returns the result in 
[DI]. [SI] is preserved unless SI equals DI. 


FloatSin Sine of a Float 


DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: 
RETURN: Carry clear 

[DI] 
RETURN: Carry Set 

ArgumentErr Invalid float, or argument not in range. 
PANIC: None 


Calculates the Sine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved 
unless SI equals DI. 


15-3 


EPOC O/S SYSTEM SERVICES 


FloatSqrt Square root of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
ArgumentErr Invalid float or argument less than 0. 


PANIC: None 


Calculates the square root of a double argument in [SI] returning the result in [DI]. [SI] is preserved 
unless SI equals DI. 


FloatTangent Tangent of a float 
DI Pointer to destination floating point operand. 
SI Pointer to floating point function argument. 
RETURN: Carry clear 
[DI] 
RETURN: Carry Set 
OverflowErr Input argument equals PI/2. 


PANIC: None 


Calculates the Tangent in radians of a double argument in [SI] returning the result in [DI]. [ST] is 
preserved unless SI equals DI. 


15-4 


CHAPTER 16 


CHARACTER MANAGEMENT 


¢ CharlsDigit Character is a digit 


AL The character to be tested. 
RETURN: 

Z flag = 0 If character is a digit. 

Z flag = 1 If character is not a digit. 


PANIC: None 


Returns the flags set depending on whether the character in AL is a digit. This is a language dependent 
service. 


e CharlsHexDigit Character is a hexadecimal digit 
AL The character to be tested. 

RETURN: 
Z flag = 0 If character is a hexadecimal digit. 
Z flag = 1 If character is not a hexadecimal digit. 


PANIC: None 


Returns the flags set depending on whether the character in AL is a hexadecimal digit. This is a language 
dependent service. 


¢ CharlsPrintable Character is printable 
AL The character to be tested. 

RETURN: 
Z flag = 0 If character is printable. 
Z flag = 1 If character is not printable. 


PANIC: None 


Returns the flags set depending on whether the character in AL is printable. This is a language dependent 
service. 


¢ CharlsAlphabetic Character is alphabetic 
AL The character to be tested. 

RETURN: 
Z flag = 0 If character is alphabetic. 
Z flag = 1 If character is not alphabetic. 


PANIC: None 


Returns the flags set depending on whether the character in AL is alphabetic. This is a language 
dependent service. 


16-1 


EPOC O/S SYSTEM SERVICES 


¢ CharlsAlphaNumeric 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


Character is alphabetic or digit 


The character to be tested. 


If character is alphanumeric. 


If character is not alphanumeric. 


Returns the flags set depending on whether the character in AL is alphanumeric. This is a language 


dependent service. 


« CharlsUpperCase 


AL 
RETURN: 
Z flag = 0 
Z flag =1 
PANIC: None 


Character is upper case 


The character to be tested. 


If character is upper case. 


If character is not upper case. 


Returns the flags set depending on whether the character in AL is upper case. This is a language 


dependent service. 


e CharlsLowerCase 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


Character is lower case 


The character to be tested. 


If character is lower case. 


If character is not lower case. 


Returns the flags set depending on whether the character in AL is lower case. This is a language 


dependent service. 


« CharlsSpace 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


Character is space 


The character to be tested. 


If character is space. 


If character is not space. 


Returns the flags set depending on whether the character in AL is a space. This is a language dependent 


service. 


e CharlsPunctuation 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


Character is punctuation 


The character to be tested. 


If character is punctuation. 


If character is not punctuation. 


Returns the flags set depending on whether the character in AL is punctuation. This is a language 


dependent service. 


16-2 


e CharlsGraphic 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


16 CHARACTER MANAGEMENT 


Character is graphic 


The character to be tested. 


If character is graphic. 


If character is not graphic. 


Returns the flags set depending on whether the character in AL is graphic. This is a language dependent 


service. 


e CharlsControl 


AL 
RETURN: 
Z flag = 0 
Z flag = 1 
PANIC: None 


Character is control 


The character to be tested. 


If character is control. 


If character is not control. 


Returns the flags set depending on whether the character in AL is control. This is a language dependent 


service. 


¢ CharToUpperChar 


AL 
AH 

RETURN: 
AL 
AH 


PANIC: None 


Characters to upper case 


A character to be converted. 


A character to be converted. 


Converted to upper case. 


Converted to upper case. 


Converts the characters in AH and AL to upper case. This is a language dependent service. 


e CharToLowerChar 


AL 
AH 

RETURN: 
AL 
AH 


PANIC: None 


Characters to lower case 


A character to be converted. 


A character to be converted. 


Converted to lower case. 


Converted to lower case. 


Converts the characters in AH and AL to lower case. This is a language dependent service. 


e CharToFoldedChar 


AL 
AH 

RETURN: 
AL 
AH 


PANIC: None 


Characters to folded characters 


A character to be folded. 
A character to be folded. 


Folded. 
Folded. 


Folds the characters in AH and AL. This is a language dependent service. 


CHAPTER 17 


BUFFER MANAGEMENT 


¢ BufferCopy Copy one buffer to another 
DS:SI Pointer to source buffer. 
ES:DI Pointer to target buffer. 
CX Number of bytes to copy. 


RETURN: None 

PANIC: None 

Copies CX bytes of data from the source buffer to the target buffer. 

The service is optimised to perform the copy in words. If the target buffer pointer is greater than the 


source buffer pointer, the copy will be done backwards so as to avoid the possibility of corrupting the 
source buffer during the copy. In most cases it is better to use the REP MOVSW 80C86 instruction. 


¢ BufferSwap Swap the contents of two buffers 
DS:SI Pointer to one of the buffers. 
ES:DI Pointer to the other buffer. 
CX The number of bytes to swap. 


RETURN: None 
PANIC: None 


Swap the contents of the two buffers pointed to by SI and DI. CX bytes of data will be swapped. This 
service is optimised to use words. 


¢ BufferCompare Compare one buffer with another 
DS:SI Pointer to left operand buffer. 
ES:DI Pointer to right operand buffer. 
CX Number of bytes in the left operand. 
BX Number of bytes in the right operand. 
RETURN: 
Flags < 0 If [SY] < [DI] 
Flags = 0 If [SI] = [DI] 
Flags > 0 If [SY] > [DI] 


PANIC: None 


Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, 
i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed 
comparisons such as JAE etc. will lead to unpredictable results. This service makes the comparison 
dependent on the case. 


17-1 


EPOC O/S SYSTEM SERVICES 


« BufferCompareFolded Compare a buffer with another folded 
DS:SI Pointer to left operand buffer. 
ES:DI Pointer to right operand buffer. 
cx Number of bytes in the left operand. 
BX Number of bytes in the right operand. 
RETURN: 
Flags < 0 If [SI] < [DI] 
Flags = 0 If [SI] = [DI] 
Flags > 0 If [SI] > [DI] 


PANIC: None 


Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, 
i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed 
comparisons such as JAE etc. will lead to unpredictable results. 


This service is case independent and is language dependent. 


« BufferLocate Locate a character in a buffer 
AH The character to be located. 
DS:SI Pointer to the buffer to be searched. 
cx The number of bytes in the buffer to be searched. 
RETURN: Carry clear 
AX Index of the character in the string. 
RETURN: Carry set 
AL undefined Character is not in the string. 


PANIC: None 


Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the 
character is located then the index into the buffer is returned in AX. The index of the first character in the 
buffer is 0. 


This service is case dependent. 


« BufferLocateFolded Locate a character in a buffer folded 
AH The character to be located. 
DS:SI Pointer to the buffer to be searched. 
CX The number of bytes in the buffer to be searched. 
RETURN: Carry clear 
AX Index of the character in the string. 
RETURN: Carry set 
AL undefined Character is not in the string. 


PANIC: None 


Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the 
character is located then the index into the buffer is returned in AX. The index of the first character in the 
buffer is 0. 


This service is case independent. 


17-2 


e BufferSubBuffer 


DS:SI 
ES:DI 
cx 
BX 

RETURN: Carry clear 
AX 

RETURN: Carry set 
AL undefined 


PANIC: None 


17 BUFFER MANAGEMENT 


Find a sub-buffer in a buffer 


Pointer to the buffer to be searched. 

Pointer to the buffer to be located. 

The number of bytes in buffer being searched. 
The number of bytes in sub-buffer. 


Offset of the sub-buffer within the buffer. 


Sub-buffer not found. 


Locates a buffer as a sub-buffer within another buffer. 


If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length 
CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to 
by SI and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a 
sub-buffer, then the service returns the carry flag set. 


This service is case dependent. 


- BufferSubBufferFolded Find a sub-buffer in a buffer folded 


DS:SI Pointer to the buffer to be searched. 

ES:DI Pointer to the buffer to be located. 

cx The number of bytes in buffer being searched. 

BX The number of bytes in sub-buffer. 
RETURN: Carry clear 

AX Offset of the sub-buffer in the buffer. 


RETURN: Carry set 
AL undefined. 
PANIC: None 


Locates a buffer as a sub-buffer within another buffer. 


Sub-buffer not found. 


If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length 
CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to 
by SI, and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a 
sub-buffer, then the service returns the carry flag set. 


This service is case independent. 


- BufferMatch Match a wild card buffer 


DS:SI Pointer to the buffer to be searched. 

CX Length of the buffer to be searched. 

ES:DI Pointer to the wild card match buffer. 

Dx Length of the match buffer. 
RETURN: Carry clear 

Match 


RETURN: = Carry set 
AL undefined 

PANIC: None 

Search a buffer for a match with the supplied wild card buffer. 


No match. 


17 -3 


EPOC O/S SYSTEM SERVICES 


If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does 
not match then the service will return with carry set. The matchany character will match any set of 
characters. The MatchSingle character will match any single character. 


This service is case dependent. 


- BufferMatchFolded Match a wild card buffer folded 


DS:SI Pointer to the buffer to be searched. 
cx Length of the buffer to be searched. 
ES:DI Pointer to the wild card match buffer. 
Dx Length of the match buffer. 
RETURN: Carry clear 
Match 
RETURN: = Carry set 
AL undefined No match. 


PANIC: None 
Search a buffer for a match with the supplied wild card buffer. 


If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does 
not match then the service will return with carry set. The Matchany character will match any set of 
characters. The MatchSingle character will match any single character. 


This service is case independent. 


- BufferJustify Justify a buffer 


DS:SI Pointer to the buffer to be justified. 
Cx Length of the buffer to be justified. 
ES:DI Pointer to the target buffer. 
BX Length of the target buffer. 
DL JustifyLeft OF JustifyCentre Of JustifyRight. 
DH The fill character. 
RETURN: 
AX Points to the character after the last byte copied to the target buffer. 


PANIC: None 


Justifies a source buffer DS:SI of length CX into a target buffer ES:DI of length BX using the justification 
method passed in DL and the fill character passed in DH. If BX is negative, then BX bytes are just copied 
to the target buffer. If DL is not one of the 3 options then the left justified method will be used by default. 


17-4 


CHAPTER 18 


STRING MANAGEMENT 


¢ StringCopy Copy one string to another 
DS:SI Pointer to source string. 
ES:DI Pointer to target string. 


RETURN: None 
PANIC: None 
Copies the source string to the target string. 


¢ StringCopyFolded Copy one string to another folded 
DS:SI Pointer to source string. 
ES:DI Pointer to target string. 


RETURN: None 
PANIC: None 
Copies the source string to the target string. Characters are folded as they are copied. 


¢ StringConvertToFolded Convert a string to folded 


DS:SI Pointer to string to be folded. 
RETURN: None 
PANIC: None 
Converts the string pointed to by SI to folded. 


¢ StringCapitalise Capitalise a string 


DS:SI Pointer to string to be capitalised. 
RETURN: None 
PANIC: None 


Converts the string pointed to by SI so that the first letter is uppercase and the remaining characters are 
lowercase. 


e StringCompare Compare one string with another 
DS:SI Pointer to left operand string. 
ES:DI Pointer to right operand string. 
RETURN: 
Flags < 0 If [SY] < [DI] 
Flags = 0 If [SI] = [DI] 
Flags > 0 If [ST] > [DI] 


PANIC: None 
Compares two strings for equality. 


18-1 


EPOC O/S SYSTEM SERVICES 


The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets 
the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will 
lead to unpredictable results. 


This service is case dependent. 


¢ StringCompareFolded Compare a string with another folded 
DS:SI Pointer to left operand string. 
ES:DI Pointer to right operand string. 
RETURN: 
Flags < 0 If [SI] < [DI] 
Flags = 0 If [ST] = [DI] 
Flags > 0 If [ST] > [DI] 


PANIC: None 


Compares two strings for equality. 


The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets 
the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will 
lead to unpredictable results. 


This service is case independent and language dependent. 


¢ StringMatch Match a wild card string 


DS:SI Pointer to the string to be searched. 
ES:DI Pointer to the wild card match string. 
RETURN: Carry clear 
Match 
RETURN: = Carry set 
AL undefined No match. 
PANIC: None 
Search a string for a match with the supplied wild card string. 
If the wild card string matches then the service will return with carry clear. If the wild card string does not 


match then the service will return with carry set. The mat chany character will match any set of characters. 
The matchSingle character will match any single character. 


This service is case dependent. 


¢ StringMatchFolded Match a wild card string folded 


DS:SI Pointer to the string to be searched. 
ES:DI Pointer to the wild card match string. 
RETURN: Carry clear 
Match 
RETURN: = Carry set 
AL undefined. No match. 


PANIC: None 


Search a string for a match with the supplied wild card string. 


If the wild card string matches then the service will return with carry clear. If the wild card string does not 
match then the service will return with carry set. The mat chany character will match any set of characters. 
The matchsingle character will match any single character. 


This service is case independent. 


18 -2 


18 STRING MANAGEMENT 


« StringLocate Locate a character in a string 
AH The character to be located. 
DS:SI Pointer to the string to be searched. 
RETURN: Carry clear 
AX Index of the character in the string. 
RETURN: Carry set 
AL undefined Character is not in the string. 


PANIC: None 
Locates the character in AH within the string pointed to by SI. 


If the character is located then the index into the string is returned in AX. The index of the first character 
in the string is 0. 


This service is case dependent. 


¢ StringLocateFolded Locate a character in a string folded 
AH The character to be located. 
DS:SI Pointer to the string to be searched. 
RETURN: Carry clear 
AX Index of the character in the string. 
RETURN: Carry set 
AL undefined Character is not in the string. 


PANIC: None 
Locates the character in AH within the string pointed to by SI. 


If the character is located then the index into the string is returned in AX. The index of the first character 
in the string is 0. 


This service is case independent. 


¢ StringLocatelnReverse Locate a character in reverse 
AH The character to be located. 
DS:SI Pointer to the string to be searched. 
RETURN: Carry clear 
AX Index of the character in the string. 
RETURN: Carry set 
AL undefined Character is not in the string. 


PANIC: None 


Locates the character in AH within the string pointed to by SI in reverse order. 


If the character is located then the index into the string is returned in AX. The index of the first character 
in the string is 0. 


This service is case dependent. 


¢ StringLocatelnReverseFolded Locate char’ in reverse folded 
AH The character to be located. 
DS:SI Pointer to the string to be searched. 

RETURN: Carry clear 
AX Index of the character in the string. 


EPOC O/S SYSTEM SERVICES 


RETURN: Carry set 
AL undefined Character is not in the string. 
PANIC: None 


Locates the character in AH within the string pointed to by SI in reverse order. 


If the character is located then the index into the string is returned in AX. The index of the first character 
in the string is 0. 


This service is case independent. 


¢ StringSubString Find a substring in a string 
DS:SI Pointer to the string to be searched. 
ES:DI Pointer to the string to be located. 
RETURN: Carry clear 
AX Offset of the substring in the string. 
RETURN: Carry set 
AL undefined Substring not found. 


PANIC: None 


Locates a string as a substring within another string. 


If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index 
of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string 
is 0. 


If the string is not a substring, then the service returns with the carry flag set. 


This service is case dependent. 


¢ StringSubStringFolded Find a substring in a string folded 


DS:SI Pointer to the string to be searched. 

ES:DI Pointer to the string to be located. 
RETURN: Carry clear 

AX Offset of the substring in the string. 
RETURN: Carry set 

AL undefined Substring not found. 


PANIC: None 


Locates a string as a substring within another string. 


If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index 
of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string 
is 0. 


If the string is not a substring, then the service returns with the carry flag set. 


This service is case independent and language dependent. 


¢ StringLength Length of a string 


ES:DI Pointer to the string whose length is to be found. 
RETURN: 
AX The length of string. 


PANIC: None 
Returns the length of the string pointed to by DI excluding the terminating zero. 


18-4 


18 STRING MANAGEMENT 


¢ StringValidateName Validate a system name 
AL Maximum number of characters in the name allowed in the name. 
AH Non 0 - An extension is valid. 


0 - An extension is invalid. 
ES:DI Pointer to the string to be validated. 
RETURN: Carry clear 
String is valid. 
RETURN: = Carry set 
NameErr String is not valid. 
PANIC: None 
Validates that the string at DI points to a valid system name. 


An extension is only allowed if AH is non zero. AL specifies the number of characters that can be in the 
name before the period. 


The BNF for a valid name is as follows: 


ANY := ALPHA | DIGIT | $ | _ 
NAME := ALPHA [ [ANY]*7 [. [ANY]*3 ]] 


18-5 


CHAPTER 19 


GENERAL MANAGEMENT 


Version numbers 


A version number is a 16 bit integer. If the 16 bit integer is converted to 4 hex digits, i.e. XY YZ, then the 
version is: 


X.YYZ 


where X is the major release number, YY is the minor release number and Z is the version type. The 
version type may have three values. 


e A- Alpha release. 
e 6B - Beta release. 
e  F - Final release. 


Thus a typical version number 0x100f would be 1.00F. 


GenVersion Get the operating system version number 
None 

RETURN: 
AX The operating system version number. 


PANIC: None 


Returns the operating system version number as a 16 bit integer. 


GenRomVersion Get the ROM version number 
None 

RETURN: 
AX The ROM version number. 


PANIC: None 


Returns the ROM version number. 


The operating system is never released on its own and is always supplied with a number of files in its built 
in ROM disk. The tool which builds the operating system together with the ROM disk allows a version 
number to be specified. This service can be used to retrieve the version number so specified. 


19-1 


EPOC O/S SYSTEM SERVICES 


GenLcdType Get the system LCD type 


None 
RETURN: 
AL The LCD type. 
PANIC: None 
Returns the system LCD type. The various types are defined in epocdefs.inc. 


GenStartReason Get the system cold start reason 
None 

RETURN: 
AL The cold start reason. 


PANIC: None 


Returns the system cold start reason. The operating system can perform a cold start for five reasons: 
e Initialise; system RAM is invalid. 
e Power fail; the system was forced to power down, but RAM is still valid. 
e Reset; the user requested a reset, but RAM is still valid. 
e =Kernel fault; a serious fault occurred while executing in the operating system kernel. 


e New OSS restart; a new operating system has been programmed into the flash memory and a 
restart has occurred. 


The shell on first starting up should request the cold start reason and if it is not an initialise it should 
inform the user of the reason for the cold start. 


« GenDataSegment Get the operating system data segment 
None 

RETURN: 
ES The operating system data segment. 


PANIC: None 


Returns the operating system's data segment address. This service is reserved for use by system utilities. 


GenGetCountryData Get the country data 


BX Pointer to a cDataEnt structure. 
RETURN: None 
PANIC: None 


Returns the country dependent data currently installed. The operating system on start-up copies the 
country dependent data from the configuration file into RAM so that the GensetcountryData can be 
called to update the information. 


GenSetCountryData Set the country data 


ES:BX Pointer to a cDataEnt structure. 
RETURN: None 
PANIC: None 


Sets the country dependent data. The source of the data is the cbat arnt structure pointed to by ES:BX. 


19-2 


19 GENERAL MANAGEMENT 


GenGetOsData Get the O/S data 


DI Pointer to a buffer to receive the data. 
SI Offset in the operating system data space. 
cx The number of bytes to be copied. 


RETURN: None 

PANIC: None 

Copies data from the operating system's data space to the buffer provided. 

All operating system handles are the actual address in the operating system data space of the appropriate 
control entry. For example, the handle returned by the Filzxecute service is the address in the operating 


system data space of the z_proc process control entry. By fetching this data, a program can determine 
many things about the state of a process. 


GenGetErrorText Get error text 
AL The error number. 
BX Pointer to a buffer to receive the error text. 


RETURN: None 
PANIC: None 


Returns the text associated with an error number. 


The buffer pointed to by BX must be MaxErrorTextsize in length. If AL is not negative or it contains an 
error unknown to the operating system, then "Unknown error [-xx]" will be returned where xx is the 
unknown error number. 


This is a language dependent service. 


e Dummy Dummy service 


None 
RETURN: None 
PANIC: None 


This service provides a means for generating a call to a known location in the operating system. It is used 
mainly for debugging the operating system. The service itself does nothing at all. 


GenParse Generic file name parser 


BX Pointer to a GenParseEnt Structure. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

NameErr Invalid name. 
PANIC: None 


This service provides a generic parse service which can be used to parse file names. 


This service should not be confused with the rilparse service. FilParse Calls the file server which in 
turn calls a file system to parse the file name and this will always be successful, assuming that the file 
name obeys the naming rules for the target file system. 


This service can only parse generic MSDOS like file names. The generic parser considers a file name to 
consist of up to five components: 


SystemName Drive Path Name Extension 
A SystemName consists of a FileSystemName followed by two ':'s. 


A Drive consists of a DriveName followed by DriveSeparator. 


EPOC O/S SYSTEM SERVICES 


A Path consists of a PathSeparator followed by zero or more DirectoryName PathSeparator pairs. 
An Extension consists of an ExtensionSeparator followed by an ExtensionName. 


The GenParseEnt structure allows a single character to be specified for each of the separators and the 
maximum size for each of the four components. Note that the maximum size of a component includes any 
separators. Note also that the SystemName separator of two ':'s cannot be specified. 


For MSDOS filing systems, the values which should be loaded into the structure are as follows: 


GenParseDeviceSeparator= ':' 
GenParsePathSeparator= '\' 
GenParseExtSeparator = 
GenParseMaxDeviceSize= 2 

GenParseMaxPathSize = 64 
GenParseMaxNameSize = 8 


vot 


GenParseMaxExtSize = 4 


The remaining fields of the structure specify pointers to three input names, a pointer to the output buffer 
and a pointer to a FullParseEnt Structure. 


Parsing is effected as follows. The three input strings are prioritised in the order 
GenParseSourceNamePtr,GenParseRelatedNamePtr and GenParseDefaultsPtr. Each of these input 
strings is parsed into its four components (some of which may be missing). The resulting string is built by 
taking components from the first string. Any missing components are filled in from the second string 
(where they exist). Any components still missing are filled in from the third string. Thus, if the "source" 
string does not have a drive, but the "related" string does, then the resulting name will use the drive as 
specified in the "related" string. 


When the resulting string has been built, the size of each component is put into the FullParseEnt 
structure. 


Finally, the name and extension components are examined for the wild card characters '?' and '*' and, if 
found, the parseWildName and ParseWildext flags are set appropriately in the 

FullParseEnt .FullParseFlags field. If either parsewildName Of ParseWildExt is set then ParseWildAny 
is also set. 


GenDeferredMode Set deferred mode 


AL 0 - Increment deferred mode. 
Non 0 - Decrement deferred mode 
RETURN: None 
PANIC: None 
This service only applies to the MC version of the operating system and can be used to defer some of the 


work which is performed in the 32Hz. tick interrupt. 


Calling the service with AL equal to zero will defer keyboard and mouse polling, parallel I/O polling and 
the piezo sound system. This has the additional benefit of stopping the serial channel from being 
temporarily diverted by the tick interrupt service routines. Normal operation can be resumed by calling 
this service with AL set to a non zero value. 


If the tick interrupt overhead must be reduced further then the anti-nesting flag can be incremented. This 
is a byte at address 0438h in the operating system data space. While this flag is set, only the time is kept 
up to date but be warned, pre-emptive multi tasking is disabled as are all timer services. 


GenNotify Notify by text 


BX Pointer to the first message. 

cx Pointer to the second message or zero. 
Dx Pointer to the first option or zero. 

DI Pointer to the second option or zero. 
SI Pointer to the third option or zero. 


19-4 


19 GENERAL MANAGEMENT 


RETURN: Carry clear 
AL 0 - First option chosen by the user. 
1 - Second option chosen by the user 
2 - Third option chosen by the user. 
RETURN: Carry set 
FailErr No notify process running. 
PANIC: None 
This service will send a message to the notification process and await the result from the notifier, 
returning the result in AL. If a notifier is not currently running then railerr will be returned. 


BX and CX specify two zero terminated text messages which will be displayed by the notifier process. 
Each string can be up to MaxNot ifyTextSize in length including the zero terminator. CX can be 
optionally zero, in which case the second message line will be blank. 


DX, DI and SI specify up to three options which the user may select. The selected option is returned in AL 
and will be 0 if the DX option is chosen, 1| if the DI option is chosen and 2 if the SI option is chosen. By 
convention, if all the options are specified as 0 then this is the same as having DX point to an option of 
"CONTINUE". Each option string can be up to MaxOptionTextSize in length including the zero 
terminator. Finally if DI is 0 then SI should also be 0. 


The presentation of the notifier depends on the process which has hooked the notify interface. 


GenNotifyError Notify by error number 
AL The error number to be notified. 
BX Pointer to the first message. 
Dx Pointer to the first option or zero. 
DI Pointer to the second option or zero. 
SI Pointer to the third option or zero. 
RETURN: Carry clear 
AL 0 - First option chosen by the user. 


1 - Second option chosen by the user. 
2 - Third option chosen by the user. 
RETURN: Carry set 
FailErr No notify process running. 
PANIC: None 
This service first calls GenGetErrorText using AL as the parameter and then calls the GenNot ify service 


with CX pointing to the resultant error text, all other registers being the same. 


Only error numbers catered for by the configuration file should be notified using this service. It is 
reasonable to expect that all errors returned by the operating system can be notified with this service. 


GenNotifyHook Hook the notify interface 


BX The message number. 
RETURN: Carry clear 
Success 
RETURN: = Carry set 
FailErr Notify interface already hooked. 
PANIC: None 
This service allows a process to get a message in response to calls by all other processes to the GenNotify 


and GenNotifyError Services. 


The message will be delivered with the message number specified in BX and the message buffer will 
contain 5 words. The 5 words will consist of the 5 parameters to the GenNotify service in the order BX, 
CX, DX, DI and SI. Note that as 5 words need to be delivered, a process which hooks the notify interface 
should initialise messaging using the MessInit service with a size of at least 10 in BL. 


19-5 


EPOC O/S SYSTEM SERVICES 


The text string pointed to by the 5 parameters can be fetched from the requesting process using the 
ProcCopyFromBylId service. The result should be returned in CX when the MessFree service is called to 
give the result of the notification. 


A process which has hooked the notify interface should not call either the Gennot ify or the 
GenNotifyError services as it would then try and send itself a message, resulting in a lock up situation. It 
is probably wise for the process to disable file server notifies for itself by calling the GensetNotifystate 
to off, as it might be waiting for a file request to complete when the file server sends a notify message, 
resulting in lock up. 


If the process which has hooked the notify interface either exits or is panicked, then the supervisor will 
automatically free the interface so that another process can hook it. 


GenNotifyUnHook Unhook the notify interface 


None 
RETURN: None 
PANIC: 
PanicGenl Process does not have the interface hooked. 


This service will release the notify interface provided the process calling this service already has the 
interface hooked. If not, then the process will be panicked. 


GenGetRamSizelnParas Get addressable system RAM size 
None 

RETURN: 
AX Size of system ram in paragraphs. 


PANIC: None 


Returns the size, in paragraphs, of the currently addressable system RAM. On machines containing more 
than 512 kilobytes of RAM, this is not the same as the total amount of RAM that is fitted in the machine. 


GenGetCommandLine Get the command line 
None 

RETURN: 
AX Pointer to the command line or 0. 


PANIC: None 


Returns a pointer to the command line. 


The command line is a memory cell in the heap and can be freed if required with HeaprreeCell. 
Processes can also be started with no command line in which case this service will return 0. 


The address of the command line is also stored in the global variable ps: [Dat acommandPtr]. If the 
command line is freed then, for consistency, this global variable should be set to 0. 


The structure of the command line is a zero terminated string which contains the full path name used to 
start the process. This can be used to find other files associated with the process being run or to open the 
image file in order to access either added files or added DYLs. 


After the 0 of the zero terminated string is a leading byte string containing any arguments for the process. 
The string is leading byte counted so that binary arguments can be passed to programs. If the rFilExecute 
service 1s called with CX equal to 0 then no command line is passed. This should only be used to execute 
programs with no heap, since they obviously have nowhere to store the command line. It is preferable to 
have CX pointing to a string containing just the zero terminator. 


19 -6 


19 GENERAL MANAGEMENT 


GenGetSoundFlags Get the sound flags 


None 
RETURN: 
AX The sound flags. 
PANIC: None 
This service returns the current setting in the sound flags. The bits in the sound flags are as follows: 


@® SoundKeyboardEnable - If set, will enable keyboard clicks. 

® SoundBuzzerEnable - If set, will enable the piezo sound system. 
@® SoundDeviceEnable - If set, will enable the SND: device driver. 
@  SoundLoud - If set, will make the piezo sound louder. 

® SoundDisable - If set, will disable all sound in the system. 


GenSetSoundFlags Set the sound flags 


BX The new sound flags. 
RETURN: None 
PANIC: None 
This service sets the sound flags to the value in BX. The bits in the sound flags are as follows: 


® SoundKeyboardEnable - If set, will enable keyboard clicks. 

@ SoundBuzzerEnable - If set, will enable the piezo sound system. 

@ SoundDeviceEnable - If set, will enable the SND: device driver. 

@ SoundLoud - If set, will make the piezo sound louder. 

® SoundDisable - If set, will disable all sound in the system. 

GenSound Make sound with the piezo 

BX The duration of the sound in ticks. 
cx The pitch of the sound. 


RETURN: None 
PANIC: None 


This service will make a sound through the piezo for the duration specified in BX ticks and at the pitch 
specified in CX. The pitch can be calculated as (512/CX) KHz. The piezo uses very little power and is an 
easy way of generating sound, although it is quite soft. If greater sound complexity, or a louder sound is 
required then the SND: device driver can be used. 


Access to this service is controlled by a semaphore which has been pre-counted with 1. When service is 
requested, the semaphore is waited on and when completed the sound request is run. The service then 
returns to the process requesting the service. When the duration elapses, the semaphore is signalled, 
allowing the next service request to be processed. The effect of the above, assuming the piezo is not 
already in use, is that the first call to this service will complete immediately allowing the application to go 
about its business, but subsequent calls will wait until the current request is completed. If multiple 
processes make requests on this service, they are run on a first come first served basis. 


GenMarkActive Mark a process as active 


None 

RETURN: None 

PANIC: None 

This service informs the operating system that the process invoking this service is to be considered active. 
The operating system has the ability to auto switch off if no activity takes place within a certain length of 


time. Activity is considered to be a context switch to a process which has been marked active, 1.e. 
whenever the process executes, the timer controlling the auto switch off will be reset. 


19-7 


EPOC O/S SYSTEM SERVICES 


By default, all processes, when first created, are marked as active so that this service does not need to be 
called unless the GenMarkNonAct ive service has been called. 


GenMarkNonActive Mark a process as non-active 


None 
RETURN: None 
PANIC: None 


This service will inform the operating system that the process invoking this service is not to be considered 
active. 


The operating system has the ability to auto switch off if no activity takes place within a certain length of 
time. Activity is considered to be a context switch to a process which has been marked active. Hence 
marking a process as non-active will ensure that whenever the process executes, the timer controlling the 
auto switch off will not be reset. 


By default all processes, when first created, are marked as active so that this service must be called if the 
process is not to be considered as active. All servers must mark themselves as non-active, since they only 
execute when required by clients and the status of the client will determine activity or not. Thus if a client 
of the file server is non-active and requests some file activity, it will not be considered as activity because 
the file server is also marked as non-active. However if the client is active then by virtue of making the 
request to the file server, the auto switch off timer will be reset. 


If, for example, a program was left running displaying the time every second, by default, the machine 
would never switch off as every second the process would execute resetting the auto switch off timer, 
possibly not a desirable state of affairs. By marking the process as non-active then the activity of the 
process would not reset the timer and the machine would be able to switch off. 


GenGetText Get operating system text 
AL The number of the text message to be retrieved. 
ES:BX Pointer to the buffer to receive the text. 


RETURN: Carry clear 

Success 
RETURN: Carry set 

AL undefined Failed to find the message. 
PANIC: None 


This service will scan the operating system's built in configuration file for the text message associated 
with the number in AL. This service is similar to GenGetErrorText when AL is negative but can also be 
passed positive numbers. The text messages available depend entirely on the configuration file built into 
the ROM with the operating system. 


GenGetNotifyState Get notify state 


None 
RETURN: 
AL The notify state. 
PANIC: None 
This service will get the current notify state for the process. 
The file server, when it detects a problem which the user could possibly correct, will call the notifier 


process to inform the user of the error and any action which must be performed (e.g. replacing an SSD 
which had been accidentally removed before all files open on it were closed). 


If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is 
1 then the notifier will be called. 


Some applications are intended to work in an unattended fashion so that a request for user attention would 
be to no avail. In this case, the state should be set to 0 so that the process itself can take any action 
required. By default, processes have the state set to 1. 


19-8 


19 GENERAL MANAGEMENT 


GenSetNotifyState Set notify state 


AL The notify state. 
RETURN: None 
PANIC: None 
This service will set the current notify state for the process. 
The file server, when it detects a problem which the user could possibly correct, will call the notifier 


process to inform the user of the error and any action which must be performed (e.g. replacing an SSD 
which had been accidentally removed before all files open on it were closed). 


If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is 
1 then the notifier will be called. 


Some applications are intended to work in an unattended fashion so that a request for user attention would 
be to no avail. In this case, the state should be set to 0 so that the process itself can take any action 
required. By default, processes have the state set to 1. 


GenGetAutoSwitchOffValue Get the auto switch off time 
RETURN: 
AX The auto switch off time in seconds. 


PANIC: None 
This service can be used to get the current auto switch off time. 
The time, in seconds, is returned in AX. It represents the amount of time which must expire with no 


activity before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By 
default, the auto switch off is set to 300 seconds. 


GenSetAutoSwitchOffValue Set the auto switch off time 


BX The auto switch off time in seconds. 
RETURN: None 
PANIC: None 
This service can be used to set the auto switch off time. 
The time, in seconds, is passed in BX. It represents the amount of time which must expire with no activity 


before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By default, the 
auto switch off is set to 300 seconds. 


GenSetRevector Capture an interrupt 
AL The vector number. 
CX:BX The segment and offset on the interrupt routine. 


RETURN: None 
PANIC: None 


The operating system hooks all interrupt vectors to itself and in the case of hardware interrupt vectors and 
the special interrupt vectors, provides a shell interrupt service routine which will do all the right things to 
satisfy the operating system rules. 


This service allows a new interrupt service to be installed and should only be called by device drivers. As 
the new interrupt service is being called by the operating service through a shell the following rules apply 
to the interrupt service routine. 


e All registers may be destroyed except BP,SP and SS. 
e The routine should return with a far ret and not an iret. 


e If a re-schedule is required, then it should return with carry set; if not then carry should be clear. 


19-9 


EPOC O/S SYSTEM SERVICES 


The interrupts which may be re-vectored in this way are specified by constants in epocdefs.inc and are as 
follows: 


@ HwIntORevector - Divide by zero interrupt. 
@ HwInt1Revector - Single step interrupt. 

@ HwInt2Revector - Nmi interrupt. 

@ HwInt3Revector - Breakpoint interrupt. 


@ HwInt4Revector - Bounds check interrupt. 


e HwIrq0Revector - HwIrq7Revector - The 8 hardware interrupts. 


Note that under no circumstances should the Nmi or Irq0 (the tick interrupt) interrupts be re-vectored. 


GenResetRevector Release an interrupt 


AL The vector number. 
RETURN: None 
PANIC: None 


If the GensetRevector service has been used by a device driver to capture an interrupt, the interrupt 
should be released using this service when no longer required. This allows the operating system to point 
the vector to an appropriate default routine. The value in AL should be the re-vector number which was 
originally passed to GenSetRevector. 


GenGetLanguageCode Get the language code 
None 

RETURN: 
AX The language code. 


PANIC: None 


This service will return the language code for the configuration data built into the ROM with the 
operating system. 


Epoc is a configurable operating system and needs to be built with a configuration file using the 
OSROM.EXE utility. Configuration files are language dependent and, as such, a language code is 
included. The language code can be usefully used by applications which are multi-lingual to determine 
which language to present. The language codes are as follows: 


= Test 

= English 
= French 
= German 
= Spanish 
= Italian 
= Swedish 
= Danish 
= Norwegian 


oMWAtInauw fF WNEFE OO 


= Finnish 
= American 

= Swiss French 
= Swiss German 
= Portuguese 
Turkish 
Icelandic 


= Russian 

= Hungarian 

= Dutch 

9 = Belgian Flemish 


AIHA BWNHEO 
ll 


20 = Australian 

21 = New Zealand 

22 = Austrian 

23 = Belgian French 


19 - 10 


19 GENERAL MANAGEMENT 


GenGetSuffixes Get suffix text 


ES:BX Pointer to buffer to receive the suffix text. 
RETURN: None 
PANIC: None 


This service will copy the language dependent suffixes from the configuration file into the buffer pointed 
to by ES:BX. 


The suffixes are fixed length zero terminated strings with a maximum length of three bytes including the 
zero terminator. 


Suffixes follow numbers for the day of the month (for example, the st in Ist. September 1990). Hence 
there are 31 suffixes so that ES:BX must point to a buffer of at least 31*3 bytes. 


This is a language dependent service. 


GenGetAmPmText Get the AM and PM text 


AL Zero - Get AM text 
Non zero - Get PM text. 
ES:BX Pointer to buffer to receive the AM and PM text. 


RETURN: None 
PANIC: None 


This service will copy the language dependent "AM" and "PM" text from the configuration file into the 
buffer pointed to by ES:BX. 


The two text strings are fixed length zero terminated strings with a maximum length of three bytes 
including the zero terminator. The "am" text is first, followed by the "pm" text. There are 2 strings of 3 
bytes each so that ES:BX must point to a buffer of at least 6 bytes. 


This is a language dependent service. 


GenGetBatteryType Get the battery type 


None 
RETURN: 

AL The battery type. 
PANIC: None 


This service gets the current battery type. 


By default, Epoc sets the battery type to BatteryUnknown. The battery types are declared in the header file 
epocdefs.inc. 


On machines whose hardware does not support the detection of the battery type, a meaningful result 
depends on a prior call having been made to GenSetBatteryType. 


GenSetBatteryType Set the battery type 


AL The battery type. 
RETURN: None 
PANIC: None 


This service sets the current battery type. By default, Epoc sets the battery type to BatteryUnknown. The 
battery types are declared in the header file epocdefs.inc. 


Epoc needs to know about the various battery types because the levels at which low battery warning 
messages are issued depends on the type. 


If the battery type is BatteryUnknown then Epoc gives the same warning levels as for BatteryAlkaline. 


A call to this function is not required on machines, such as the Workabout, whose hardware supports 
detection of the battery type. 


19-11 


EPOC O/S SYSTEM SERVICES 


GenCrc Generate a CRC 
cx The number of bytes in the buffer. 
DX The current CRC. 
DS:SI Pointer to the buffer to be CRC checked. 
RETURN: 
AX The updated CRC check. 


PANIC: None 


This service will generate a CRC polynomial checksum (X power 16 + X power 12 + X power 5 + 1, as 
recommended by CCITT) from the buffer pointed to by DS:SI containing CX bytes. If the checksum is 
being started then the value in DX should be passed as 0. 


¢ GenintByNumber Interrupt by number 
AL The interrupt number. 
DS:SI Pointer to the input register values. 
DS:DI Pointer to the output register values. 
RETURN: 
AX The flags register after the call. 
PANIC: 


Depends on the 
interrupt called. 


This service can be used to call any software interrupt and is provided to make calling the operating 
system easier from high level languages. 


The register values are stored sequentially as 6 words and represent the values for AX, BX, CX, DX, SI 
and DI. BP is never needed by the operating system and so is not required. DS:SI and DS:DI can point to 
the same memory location. The value returned is the flags register because although the carry flag is the 
most important, some of the operating system routines also set the arithmetic flags. The carry flag is in bit 
O of the returned result in AX. 


GenEnvBufferGet Get environment variable 
ES:DI Pointer to the environment variable name. 
DL Length of environment variable name. 
ES:SI Pointer to the buffer to receive the variable's value. 
RETURN: Carry clear 
AX The length of the data returned in ES:SI. 
RETURN: Carry set 
NotExistsErr No environment variable of the specified name exists. 


PANIC: None 


This service will locate an environment variable. The name of the variable is pointed to by ES:DI and has 
a length of DL bytes. 


The name may include wild cards, in which case the first matching name will be found. The value of the 
environment variable is copied to ES:SI and the length of this data is returned in AX. 


The maximum size of an environment variable's data is 255 bytes. 


GenEnvBufferSet Set environment variable 
ES:DI Pointer to the environment variable name. 
DL Length of environment variable name. 
ES:SI Pointer to the buffer containing the variable's data. 
CL The length of the data as ES:SI. 


19 - 12 


19 GENERAL MANAGEMENT 


RETURN: = Carry clear 


Success 
RETURN: = Carry set 
NoMemoryErr No space available to store environment variable. 
FailErr Environment variable name contained wild cards. 
PANIC: 
PanicEnv0 DL exceeded MaxEnvNameSize 


This service will either add or replace an environment variable. The name of the variable is pointed to by 
ES:DI and has a length of DL bytes. 


The name may not include wild cards nor exceed MaxEnvNameSize. The value of the environment variable 
is pointed to by ES:SI and the length of the data to be copied is in CL. Since the data is a buffer of length 
CL there is no restriction on what data may be placed in the buffer. 


The maximum size of an environment variable's data is 255 bytes. 


GenEnvBufferDelete Delete environment variable 
ES:DI Pointer to the environment variable name. 
DL Length of environment variable name. 


RETURN: Carry clear 
Success 
RETURN: = Carry set 
NotExistsErr No environment variable of the specified name exists. 
PANIC: None 
This service will delete an environment variable. The name of the variable is pointed to by ES:DI and has 


a length of DL bytes. 


The name may include wild cards in which case the first matching name is deleted. 


GenEnvBufferFind Find environment variable 
BX The find handle. 
ES:DI Pointer to the environment variable name. 
DL Length of environment variable name. 
ES:SI Pointer to the buffer to receive the variable's data. 
RETURN: Carry clear 
AX The next find handle. 
RETURN: Carry set 
EofErr No more matching environment variables. 


PANIC: None 


This service will find all occurrences of environment variables which match the supplied wild card name. 
The wild card name is pointed to by ES:DI and has a length of DL. 


A wild card of "*" will locate all environment variables. When this routine is first called, BX must contain 
zero; on subsequent calls, it must contain the value returned in AX. The wild card match string must 
remain the same on successive calls. zofErr is returned when there are no more matching names. 


After a successful call, the buffer pointed to by ES:SI contains two leading byte strings. The first string 
contains the name of the environment variable while the second string contains its value. The maximum 
size of an environment variable's data is 255 bytes. 


19 - 13 


EPOC O/S SYSTEM SERVICES 


GenEnvStringGet Get string environment variable 
ES:DI Pointer to the environment variable name string. 
ES:SI Pointer to the buffer to receive the variable's value. 


RETURN: Carry clear 
Success 
RETURN: = Carry set 
NotExistsErr No environment variable of the specified name exists. 
PANIC: None 
This service will locate an environment variable. The name of the variable is pointed to by ES:DI. The 


name may include wild cards, in which case the first matching name will be found. 


The value of the environment variable will be copied to ES:SI and will be zero terminated. Environment 
variables should not include the byte 0 as this would terminate the string prematurely. The maximum 
length of the string is 256 bytes including the terminating zero. 


GenEnvStringSet Set string environment variable 
ES:DI Pointer to the environment variable name. 
ES:SI Pointer to the string containing the variable's data. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
NoMemoryErr No space available to store environment variable. 
FailErr Environment variable name contained wild cards. 
PANIC: 
PanicEnv0 The name string exceeded MaxEnvNameSize 


This service will either add or replace an environment variable. The name of the variable is pointed to by 
ES:DI. The name may not include wild cards nor exceed MaxEnvNameSize. 


The value of the environment variable is pointed to by the string at ES:SI. The maximum size of the string 
should be limited to 255 bytes not including the zero terminator. Should the string be longer it will 
truncated module 256. 


GenEnvStringDelete Delete string environment variable 


ES:DI Pointer to the environment variable name. 
RETURN: Carry clear 

Success 
RETURN: = Carry set 

NotExistsErr No environment variable of the specified name exists. 
PANIC: None 


This service will delete an environment variable. The name of the variable is pointed to by ES:DI. The 
name may include wild cards in which case the first matching name is deleted. 


GenEnvStringFind Find string environment variable 
BX The find handle. 
ES:DI Pointer to the environment variable name. 
ES:SI Pointer to the buffer to receive the variable's name. 
ES:CX Pointer to the buffer to receive the variable's data. 
RETURN: Carry clear 
AX The next find handle. 


19-14 


19 GENERAL MANAGEMENT 


RETURN: Carry set 
EofErr No more matching environment variables. 
PANIC: None 
This service will find all occurrences of environment variables which match the supplied wild card name. 


The wild card name is pointed to by ES:DI. A wild card of "*" will locate all the environment variables. 


When this routine is first called, BX must contain zero; on subsequent calls it must contain the value 
returned in AX. The wild card match string must remain the same on successive calls. EofErr is returned 
when there are no more matching names. 


After a successful call, the buffer pointed to by ES:SI contains the name of the environment variable 
which was found, as a zero terminated string. The maximum size of the name of an environment variable 
iS MaxEnvNameSize. 


The buffer pointed to by ES:CX contains the value of the environment variable which was found, as a zero 
terminated string. The maximum size of the data is 256 bytes, including the zero terminator. 


GenAlarmHook Hook the alarm interface 


BX The message number. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
FailErr Alarm interface already hooked. 
PANIC: None 
This service allows a process to capture the alarm interface built into the operating system. Having hooked 


the alarm interface the ALM: device driver can be used to request alarms from the alarm server. 


The availability of an alarm server and what it does, varies from machine to machine and the appropriate 
documentation for the specific machine should be consulted. 


GenAlarmUnHook Unhook the alarm interface 
None 

RETURN: None 

PANIC: 
PanicGenl Process does not have the interface hooked. 


This service will release the Alarm interface if the process calling this service already has the interface 
hooked. If it does not, the process will be panicked. 


GenAlarmld Get the pid of the alarm server 


None 
RETURN: 

AX The alarm server pid. 
PANIC: None 


This service will return the ID of the alarm server. If the alarm interface is not currently hooked then this 
service will return zero in AX. 


GenTickle Reset the auto switch off timer 


None 
RETURN: None 
PANIC: None 


This service will reset the auto switch off timer to the value as specified to the last 
GenSet Aut oSwitchOffValue. This routine is useful for processes which have called GenMarkNonAct ive 
and require to "tickle" the auto switch off from time to time. 


19 - 15 


EPOC O/S SYSTEM SERVICES 


GenSetOnEvents Control on events 


AL The find handle. 
RETURN: None 
PANIC: None 


This service controls whether the system will report on-events(for example, reporting to the window 
server when the machine switches on). If AL is non-zero then on-events will be reported. If AL is zero, 
they will not. 


By default on-events are reported on Series 3 and Series 3a operating systems and not reported on other 
versions. 


©GenGetAutoMains Get state for auto-sw-off if mains present 
RETURN: 


AX The current auto-switch-off state for when mains is present. 
PANIC: None 


Returns a non-zero value in AX if auto-switch-off is disabled when mains is present, and zero if enabled. 


©GenSetAutoMains Disable/enable auto-sw-off if mains present 


AL Flag specifying whether to enable or disable. 
RETURN: None 
PANIC: None 


Enable or disable auto-switch-off if mains is present. If AL is non-zero, auto-switch-off is disabled, 
otherwise it is enabled. 


By default auto-switch-off is enabled. 


Even if enabled, the machine will not switch off when mains is absent if auto-switch-off has been stopped 
by calling GensetAutoSwitchOffValue with value -1. 


19 - 16 


CHAPTER 20 


DATABASE FILE MANAGEMENT 


File structure 


Database files (DBFs) start with a 22 byte header which contains the following information: 


Offset in header Information 

0 - 15 Zero terminated file signature. 

16, 17 Version of DBF software used to produce the file. 
18, 19 Offset from the start of the file to the first record. 
20, 21 Minimum version of DBF software required. 


Note that all 16 bytes of the file signature are used for verification, not just the zero terminated string. 
Therefore it is recommended that all file signatures are padded with zeros to fill the 16 bytes. 


See the Dbfversion service for the format of the version numbers. 


The offset within the file of the first record is to allow additional information to be added to the header 
(called the Extended Header). Note that the first record will always be a type 2 record - see below. 


The data consists of records, each with a 2 byte header stored as a word. The high nibble of the most 
significant byte (i.e. the 2nd byte in the record) gives the record's type. This can take the following values: 


0 A deleted record. 

1 A main record. 

2 The Field Information Record. 

3 The Descriptive Record. 

4-7 Reserved for record types which won't be merged. 
8 - 13 Reserved for record types which will be merged. 
14 Reserved for voice entries. 

15 Used internally (not to be used by applications). 


Note that types 8 - 14 will be copied and merged by the pbfcopyFile service when DbfRecordTypeAl1l is 
specified whereas record types 3 - 7 will only be copied if the target file is created, i.e. not if merging two 
files. 


The remaining 12 bits of the header word give the size of the record. However the maximum size of a 
record is 4094 bytes, so that there is room in a 4096 byte buffer for the longest record including its header. 


The Field Information Record is used to store the field structure used by the other records. There will 
be exactly | Field Information Record per file and it will always be the first record in the file (any other 
type 2 records will be ignored). Each byte in the record indicates the type of the corresponding field in the 
records which follow, so the length of this record is the number of fields. The possible values for each byte 
are: 


0 Word 
1 Long 


20-1 


EPOC O/S SYSTEM SERVICES 


2 Double 
3 String 
4 - 255 Reserved 


The maximum length of this record is 32 bytes representing 32 fields. 


The 22 byte header and the Field Information Record must be passed to the Dpbfopen service when a file 
is created or replaced and will be returned by pbfopen when an existing file is opened. 


Buffering 


When a database file is opened, the address of a buffer must be provided which should be at least as large 
as the maximum record size to be used. Thus, a buffer of 4096 bytes is guaranteed to open all database 
files. This buffer will be used to read this many bytes worth of records from the File System at a time so as 
to reduce the calls to the File System and vastly increase the speed of operation of most of the DBF 
services. 


If the buffer provided is smaller than 4096 and there are records which are longer than the buffer, an error 
will be given when the file is opened. 


Note that the read services simply return the offset of the record within the buffer. If the buffer needs to 
be used by the application, e.g. for editing a record, the DpfcopyDown service should be called to copy the 
current record to the start of the buffer and to signal that the buffer is invalid. The pbftrash service 
simply marks the buffer as invalid. These two services will therefore cause the entire buffer to be read in 
the next time a record is read, inevitably resulting in a loss of performance. 


All DBF services may overwrite the buffer containing the current record apart from the following: 


DbfFlush 
DbfVersion 
DbfAppend 
DbfSense 
Dbf£Count 


which are guaranteed not to alter the buffer. 


Index Table 


In addition to buffering, a sparse index table consisting of a 4 byte address for every 16 records will be 
constructed when the file is opened to increase the speed of random access to the file. As records are 
added to the file, the table will also be appended. When a record is deleted, each pointer in the table after 
the deleted record will be moved to the next record, so that they always point to every 16th record. Note 
that the index table will reside in a different segment so as not to use up the application's space. 


End of file record 


When any of the record services attempt to read past the end of the file, zofzrr will be returned and the 
current record number will be the number of the last record plus 1. Also, attempting to read before the 
first record in the file, either with the DpfBackRead Service or the DbffrindRead Service searching 
backwards will result in zofErr and the current record number will be zero (i.e. the first record if there is 
one). However the offset in the buffer of the first/last record will not be returned, when £ofeErr is returned. 


The "current record" is always given by the record number returned by the pbfsense service but if any 
service gives EofErr, the current record will be the last record number plus | - this is called the end of 
file record (unless the error is caused by going before the first record). When this is the case, any services 
which work on the current record, e.g. DbfEraseRead, DbfUpdate, DbfFindRead searching forwards will 
return EofErr. Similarly if there are no records in the file, ppfsense record will return 0 but the above 
services will return EofErr. 


20 DATABASE FILE MANAGEMENT 


Number of records 


The maximum number of records which can be present is 65534 and they are numbered from 0 to 65533. 
An error will be given by the ppfappend service if an attempt is made to write more than 65534 records. 


DbfOpen Open a database file 


CL Type of record. 

SI Pointer to the main buffer. 

DI State. 

Dx Length of the main buffer. 

BX Points to a DbfopenkEnt Structure containing the remaining 
parameters. 


RETURN: Carry clear 


DI State. 
RETURN: Carry set 
RecordErr There are records longer than buffer supplied or buffer length is 
invalid. 
InvalidFileErr The file is not a valid DBF file. 
PANIC: 
None 


This service works in the same way as the standard file open service with the following features: 


e The service can be called in a loop with DI equal to pbfstatestart the first time and then passed 
as it is returned until it becomes ppbfstatestart again or alternatively if DI is passed as 
Dbf£StateDisabled, the service will not return until it has finished. 


Also DI can be passed as pbfst at eOpenNoIndex to disable the building of the index. This means 
it will be faster to open, but only the following services can be used on a file opened this way: 
DbfClose, DbfFlush, DbfTrash, DbfCopyDown, DbfCopyFile, DbfAbsRead, DbfAbsReadSense, 
DbfNextRead, DbfBackRead, DbfFirstRead, DbfSense. Note that reading records non-sequentially 
will be much slower than when the file is opened with index building. Calls to any other services 
will produce unpredictable results. 


e The pbfopenmode field of the ppfopenkEnt structure need not specify the file format. The DBF 
file format will be assumed. If a file is created or replaced, modeUpdate must be specified since 
the header is written to the file. 


e The pbfopenHeader field of the ppfopenknt structure is a pointer to a 56 byte buffer. The header 
consists of the 22 byte header described above followed immediately by the Field Information 
Record as a type 2 record. The maximum length of the Field Information Record is 32, plus its 
2 byte header = 34. Therefore the buffer must be 22 + 34 = 56 bytes. Even if an Extended Header 
is required, no gap should be left in the header when creating a file and no gap will be returned 
when opening an existing file. The file itself, however will contain a gap for the Extended 
Header, the length of which can be calculated from the 'start of data’ field in the 22 byte header. 


When opening an existing file, the header buffer must contain the file signature which will be 
verified against the signature in the file and InvalidrileErr will be returned if it is not identical. 
Note that all 16 bytes of the signature are always checked, not just the zero terminated string. 
The remainder of the header buffer will be filled in. Note that the type 2 record is not verified to 
be the same as the header and so need not be supplied. 


When creating or replacing a file, the header buffer must contain all 56 bytes to be written to the 
file as a header. 


EPOC O/S SYSTEM SERVICES 


In both the above cases, the minimum version number at offset 20 in the header will be checked 
and InvalidFileErr returned if this DBF software cannot handle it. See the pbfversion service 
for the format of the version numbers. Note that only the major version number is checked (i.e. 
the most significant 4 bits only of the version number word. Also, the type 2 record is checked to 
be valid and invalidFileErr returned if it is not. 


e The main buffer at SI is used to read DX bytes worth of records at a time from the File System. 
e CL specifies the type (0 - 14) of records to be accessed (it will usually be 1). 


e A sparse index table consisting of a 4 byte address for every 16 records will be constructed when 
the file is opened to increase the speed of random access to the file. This will reside in a separate 
segment so as not to use any of the application's space. 


Note that after opening the file, the current record number will be 0 (as returned by pbfsense) so that a 
call to DbfNext Read would read record number | in the file and pbfEraseRead would erase record 0. 
DbfFirstRead should be called to read record 0. 


The length of buffer supplied must be in the range 512 to 16384. Any length outside this range will result 
in RecordErr when the file is opened. The maximum length of a record is 4094 bytes, so there is always 
room in a 4096 byte buffer for all records (including the 2 byte header). 


DbfClose Close a database file 
BX The DBF handle to be closed. 
RETURN: Carry clear 
Success 
RETURN: Carry set 
AL Error number. 
PANIC: 
PanicDbf1l BX is not a valid DBF handle. 


Closes a database file. 


The handle must be one returned from the ppfopen service. 


DbfFlush Flush a database file 


BX The DBF handle. 
RETURN: Carry clear 


Success 
RETURN: Carry set 
AL Error number. 
PANIC: 
PanicDbf1 BX is not a valid DBF handle. 


Flushes all buffers. 


DbfTrash Trash a database file 


BX The DBF handle. 
RETURN: None 
PANIC: 
PanicDbf1 BX is not a valid DBF handle. 


Signals that the main database file buffer is no longer valid, so that it can be used by an application. See 
also the Db£fCopyDown Service. 


20-4 


20 DATABASE FILE MANAGEMENT 


DbfCopyDown Copy down a DBF record 


BX The DBF handle. 

SI The offset into the main buffer of the record to copy down. 
RETURN: 

AX The length of the record copied down. 
PANIC: 

PanicDbfl BX is not a valid DBF handle. 

PanicDbf2 SI is not a valid offset. 


Copies a record at the given offset in the main buffer down to the start of the buffer and sets a flag to 
signal that the buffer is no longer valid (i.e. there is no need to call ppbftrash). The length of the record is 
read from the buffer and is returned by the service. 


DbfCompress Compress a database file 
BX The DBF handle. 
DI State. 
RETURN: Carry clear 
DI State. 
RETURN: Carry set 
AL Error number 
PANIC: 
PanicDbf1 BX is not a valid DBF handle. 


Recovers space used by deleted records provided the file is stored on a compressible media. If the media is 
not compressible, this service will do nothing and will return carry clear. 


After calling this service, the current record will be the end of file record (unless the media was not 
compressible - in which case the current record is unchanged). 


DI can be passed as pbfStateStart Or DbfStateDisabled. If it is passed as ppfstatestart, the service 


must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, 
the service will not exit until it is finished. 


DbfCopyFile Copy a database file 


BX The DBF handle. 
CL Record type to copy. 
CH The direction of the copy (to or from the target file). 
Dx Open mode for target file. 
DI State. 
SI Pointer to the target file name. 
RETURN: Carry clear 
DI State. 
RETURN: Carry set 
AL Error number. 
PANIC: 
PanicDbfl BX is not a valid DBF handle. 


Copies records except deleted records from or to the open source file. This service will append records to 
the end of an existing file if DX is Modeopen or ModeAppend. Note that ModeAppend will perform exactly 
the same as ModeOpen. Copying with ModeUnique will copy the records to a unique file and return the 
name in the buffer at SI, in exactly the same way as Dbfopen. Note that the source file can be opened with 
index building disabled, i.e. with DI as ppfstateopenNoIndex with no loss in performance of the copy. 


20-5 


EPOC O/S SYSTEM SERVICES 


CL is used to specify the type of record to be copied. If ppfRecordTypeall is specified, all record types 
will be copied. Note that when merging files (i.e. DX is Modeopen Of ModeAppend) with 
DbfRecordTypeA11, only record types | and 8 - 14 will be copied across. Record types 2 - 7 will not be 
copied. Record type 2 is the Field Information Record and record type 3 is the Descriptive Record 
and types 4 - 7 are reserved for future use. Record types 2 - 7 will be copied if DX is Modecreate, 
ModeReplace Of ModeUnique. 


CH must be passed as pbfCopyFromHandle to copy from the open file to the named file or 
Dbf£CopyToHandle to copy the other way. Note that in the latter case DX must obviously be passed as 
Modeopen. Note that it is always slower using DpbfCopyToHandle because of the need to update the index 
table for the open file. 


The following procedure is used to implement the copy: 


e The target file is opened in the mode specified. If copying to an existing file, the signatures of the 
two files are verified and the r1r's are checked to be compatible. If copying to a new file, the 
header (including the rrr) and any Extended Header are copied from the source file to the target 
file. 


e All records of the specified type are copied from the source file to the target file. 
e = The target file is closed. 


e = If any error occurs during the above procedure and the target file has been created by 
Db£CopyFile, the target file will be deleted, if possible. 


DI can be passed as DbfStateStart, DbfStateDisabled Of DbfStateCopyAbort: 
e If it is passed as DbfstateDisabled the service will not exit 
until it is finished. 


e If it is passed as pbfstatestart the service must be called repeatedly until state becomes 
DbfStateStart again. This parameter can be used to plot the progress of the copy, for example 
by drawing a bar graph. DI will be incremented for every 'buffer size’ number of bytes that are 
copied (approximately). Hence the scale of the graph can be calculated by dividing the size of the 
file by the buffer size allocated. The graph plotting procedure must take account of the error in 
the number of times required to call the service. A fudge factor of 2 should be added to calculate 
how many times the service will be needed to be called. 


e Di can be passed as DpbfstateCopyAbort to abort the copy which was started with 
DbfStateStart. 


Warning: using DbfCopyFile to merge files can result in a file with more than 65534 records of a 
particular type in it. When this file is opened with the pbfopen service, only the first 65534 records will be 
accessible. No error is given from the copy or the open. 


DbfFileSize Get the size of a DBF 


BX The DBF handle. 
RETURN: Carry clear 

DI:DX The file size in bytes. 
RETURN: Carry set 

AL Error number. 
PANIC: 

PanicDbfl BX is not a valid DBF handle. 


Gets the size of an open database file. 


20 - 6 


DbfExtHeaderRead 


AL 


BX 
ex 
SI 

RETURN: Carry clear 
AX 

RETURN: Carry set 
EofErr 

PANIC: 


PanicDbf1 


20 DATABASE FILE MANAGEMENT 


Read a DBF extended header 


0 to start 

1 to continue. 

The DBF handle. 

The number of bytes to read. 

The address of the buffer to receive the data. 


The number of bytes actually read. 
The end of the Extended Header has been reached. 


BX is not a valid DBF handle. 


Reads CX bytes from the Extended Header of a database file into the buffer supplied. 


AL must be passed as 0 the first time and 1| to continue. 


EofErr is returned when the end of the Extended Header is reached, otherwise the actual number of bytes 


read is returned. 


DbfExtHeaderWrite 


AL 


BX 
CX 
SI 

RETURN: Carry clear 
AX 

RETURN: Carry set 
EofErr 

PANIC: 


PanicDbf1 


Write a DBF extended header 


0 to start 

1 to continue. 

The DBF handle. 

The number of bytes to write. 


The address of the buffer containing the data to write. 
The number of bytes actually written. 
A write past the end of the Extended Header was attempted. 


BX is not a valid DBF handle. 


Writes the buffer supplied into the Extended Header of the file. 


AL must be passed as 0 the first time and 1 to continue. 


EofErr is returned when the end of the space allocated for the Extended Header is reached, otherwise the 
actual number of bytes written is returned. 


DbfDescRecordRead 


BX 

RETURN: Carry clear 
AX 

RETURN: Carry set 
EofErr 

PANIC: 


PanicDbf1 


Read a DBF descriptive record 
The DBF handle. 


The length of the Descriptive Record 
There is no Descriptive Record in the file. 


BX is not a valid DBF handle. 


Reads the Descriptive Record into the main buffer at offset zero. If there is no Descriptive Record, 


EofErr Will be returned. 


20-7 


EPOC O/S SYSTEM SERVICES 


DbfDescRecordWrite Write a DBF descriptive record 
BX The DBF handle. 
cx The length of the Descriptive Record to be written. 


RETURN: Carry clear 


Success 
RETURN: = Carry set 
AL Error number. 
PANIC: 
PanicDbf1 BX is not a valid DBF handle. 


Writes out a Descriptive Record. The record to be written must be stored at the start of the main buffer 
as a DbfRecord Structure; there must be 2 bytes before the data starts where the record header will be 
constructed. See pbfAppend. 


Any existing Descriptive Record will be erased, in other words, there can be a maximum of one 
Descriptive Record per file. 


If CX is passed as zero, any existing Descriptive Record Will be erased and no new one will be written 
out. If there is no Descriptive Record, no error is given. 


DbfVersion Get the DBF version number 
None 

RETURN: 
AX The DBF version number. 


PANIC: None 


Gets the version number of the DBF software. This will be in the form: 


XYYF 
where 

x is the major version number (4 bits) 

YY is the minor version number (8 bits) 

F is the release type, either A,B or F for Alpha, Beta or Final 


respectively (4 bits). 
For example, if 110FH is returned, the DBF software version is 1.10F. 


Note that only the major version number is used to determine whether or not the DBF file system can 
handle a particular file. 


DbfAbsRead Read an absolute DBF record 


BX The DBF handle. 
ex The absolute record number to be read. 
RETURN: Carry clear 
AX The length of the record read. 
SI The offset in the main buffer of the record read. 
RETURN: Carry set 
EofErr The requested record number is greater than the number of records 
in the file. 
PANIC: 
PanicDbfl BX is not a valid DBF handle. 


This service will seek to the given record and read it. Records are read into the buffer (supplied when the 
file was opened) and the record's offset within the buffer is returned in SI. 


If the record number requested corresponds to a record beyond the last one, the error zofErr will be 
returned, the current record will be the end of file record and SI will be invalid. 


20-8 


DbfAbsReadSense 


BX 
CX 

RETURN: Carry clear 
AX 
SI 
DI:DX 

RETURN: Carry set 


EofErr 


PANIC: 


PanicDbf1 


20 DATABASE FILE MANAGEMENT 


Read and sense an absolute DBF record 
The DBF handle. 


The absolute record number to be read. 
The length of the record read. 
The offset in the main buffer of the record read. 


File position of start of record. 


The requested record number is greater than the number of records 
in the file. 


BX is not a valid DBF handle. 


Same as the pbfabsRead Service but also returns the file position of the start of the record. 


DbfNextRead 


BX 

RETURN: Carry clear 
AX 
SI 

RETURN: Carry set 
EofErr 

PANIC: 


PanicDbf1 


Read the next DBF record 
The DBF handle. 


The length of the record read. 


The offset in the main buffer of the record read. 
The current record was already the last record in the file. 


BX is not a valid DBF handle. 


Seeks to the next record and reads it. Records are read into the buffer (supplied when the file was opened) 
and the record's offset within the buffer is returned in SI. 


If the current record is already the last record in the file or there are no records of the current type in the 
file, EofErr will be returned, the current record will be the end of file record and SI will be invalid. 


DbfBackRead 


BX 

RETURN: Carry clear 
AX 
SI 

RETURN: Carry set 
EofErr 

PANIC: 


PanicDbf1 


Read the previous DBF record 
The DBF handle. 


The length of the record read. 


The offset in the main buffer of the record read. 
The current record was already the first record in the file. 


BX is not a valid DBF handle. 


Seeks to the previous record and reads it. Records are read into the buffer provided when the file was 
opened and the offset into this buffer of the record required is returned in SI. 


If, on entry to the call, the current record is already the first record in the file or there are no records of the 
current type in the file, Eofzrr will be returned, the current record will be 0 and SI will be invalid. 


20-9 


EPOC O/S SYSTEM SERVICES 


DbfFirstRead Read the first DBF record 


BX The DBF handle. 
RETURN: Carry clear 

AX The length of the record read. 

SI The offset in the main buffer of the record read. 
RETURN: Carry set 

EofErr There are no records in the file. 
PANIC: 

PanicDbf1 BX is not a valid DBF handle. 


Seeks to the first record and reads it. Records are read into the buffer (supplied when the file was opened) 
and the record's offset within the buffer is returned in SI. 


If there are no records in the file of the current type, zoferr will be returned, and SI will be invalid. 


DbfLastRead Read the last DBF record 


BX The DBF handle. 
RETURN: Carry clear 

AX The length of the record read. 

SI The offset in the main buffer of the record read. 
RETURN: Carry set 

EofErr There are no records in the file. 
PANIC: 

PanicDbf1l BX is not a valid DBF handle. 


Seeks to the last record and reads it. Records are read into the buffer (supplied when the file was opened) 
and the record's offset within the buffer is returned in SI. 


If there are no records in the file of the current type, zofErr will be returned, and SI will be invalid. 


DbfAppend Append a DBF record 


BX The DBF handle. 
CX The length of the record to be appended. 
RETURN: Carry clear 
Success 
RETURN: = Carry set 
OverFlowErr There are already 65534 records in the file. 
RecordErr The total length of the record (including the 2 byte header) is 
greater than the length of the main buffer. 
PANIC: 
PanicDbfl BX is not a valid DBF handle. 


This service appends a record of the current type to the end of the file and makes this the current record. 


The record to be written must be placed at the start of the main buffer as a pbfRecord structure which is 
defined as: 


typedef struct 
{ 
UWORD header; /* Used for record header word */ 
UBYTE data[2]; /* Data to be written... * f 
} DbfRecord; 


The header word will be used to construct the header for the record so that it can be written in one. 


CX is the length of the data only. 


20 - 10 


20 DATABASE FILE MANAGEMENT 


DbfEraseRead Erase a DBF record 


BX The DBF handle. 
DI State. 
RETURN: Carry clear 
AX The length of the record read. 
SI The offset in the main buffer of the record read. 
DI State. 
RETURN: Carry set 
EofErr The current record is the end of file record. 
PANIC: 
PanicDbf1 BX is not a valid DBF handle. 


Erases the current record and reads the next one. 


A record is erased by overwriting its (4 bit) type to 0. The space used by the record can only be recovered 
by calling ppfcompress. The file must be stored on a compressible medium. 


If there are no records of the current type in the file or if the current record number is the last record plus 
1, EofErr will be returned. If the current record is the last record in the file, it will be erased and zofErr 
will be returned. 


Note that pbfEraseRead may return EofErr in 2 different circumstances: 
e If the current record is already the end of file record (or there are no records). 
e If the current record is the last record. 


In the first case, the service does nothing. In the second case, the last record is erased and the current 
record becomes the end of file record. It is up to the application to deduce which of these cases has 
occurred by checking whether the current record is the end of file record before calling the service 
(using DbfSense and DbfCount) or by noting the decrease in the total number of records from pbfcount. 


DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service 
must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, 
the service will not exit until it is finished. 


DbfUpdate Update a DBF record 


BX The DBF handle. 

CX The length of the record to be written. 

DI State. 
RETURN: Carry clear 

DI State. 
RETURN: Carry set 

EofErr The current record is the end of file record. 
PANIC: 

PanicDbf1 BX is not a valid DBF handle. 


Erases the current record and appends the new one to the end of the file making this the new current 
record. The new record to be appended will be taken from the beginning of the main buffer. 


The main buffer must begin with a word where the record header will be built, followed by the record 
itself. 


CX is the length of the data only and does not include the word at the start. 
Note that the current record will only be erased after the supplied record has been successfully appended. 


If there are no records of the current type in the file or if the current record number is the last record plus 
1, EofErr will be returned. If the current record is the last record in the file, it will be erased and £oferr 
will be returned. 


20 - 11 


EPOC O/S SYSTEM SERVICES 


DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service 
must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, 
the service will not exit until it is finished. 


DbfFindRead Find a DBF record 


AL The number of fields to search. 
BX The DBF handle. 
Cx The length of the buffer to match. 
DL The maximum field length to match with. 
DH The type and direction of the search. 
DI State. 
SI Pointer to the match buffer. 
RETURN: Carry clear 
AX The length of the record read. 
DI State. 
SI The offset in the main buffer of the record read. 
RETURN: Carry set 
EofErr No matching record was found. 
PANIC: 
PanicDbfl BX is not a valid DBF handle. 
PanicDbf2 Parameters are invalid. 


Matches the given wild-card string with the string components of each record starting at the current 
record. If the current record is the end of file record, EofErr will be returned, unless DH specifies 
DbfFindBackwards. 


If a match is found, the record containing the match is made the current record and is read into the buffer; 
the offset will be returned in SI. 


AL specifies how many string fields are to be searched (the number of string fields in the Field 
Information Record is now irrelevant). A value of DpfFindAllstrings must be used to specify continue 
matching string fields until the end of the record is reached. The Field Information Record Is used to 
specify the 'types' of the first 32 fields. After that, all fields are assumed to be strings until the end of the 
record. 


DL specifies the maximum length of a string field to be used in the match, i.e. longer strings are truncated 
for matching purposes. 255 specifies no truncation. 


DH is split into 2 halves. 
The most significant nibble of DH specifies the type of match and must be one of the following: 


DbfFindCaseIndependent Case independent match. 
Dbf£fFindCaseDependent Case dependent match. 


The least significant nibble of DH specifies the search direction and must be one of the following: 


DbfFindForwards Search forwards from current record to next match. 
DbfFindBackwards Search backwards from current record to previous match. 
DbfFindFirst Search to first match in file. 

DbfFindLast Search to last match in file. 


If a match is not found, zoferr will be returned and SI will be invalid. The current record will then be the 
first record if the search was backwards or the last record number plus one (the end of file record) if the 
search was forwards. 


The Field Information Record contains the record structure which is used to find the string components 
of the record. This is always passed to pbfopen as part of the header when a file is created and is returned 
when an existing file is opened. 


DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service 
must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, 
the service will not exit until it is finished. 


20 - 12 


20 DATABASE FILE MANAGEMENT 


DbfSense Sense the current DBF record number 
BX The DBF handle. 

RETURN: 
AX The current record number. 


PANIC: None 


Sense the current record number. This will be the last record number plus 1 if an EofErr has just been 
given (unless there are no records, in which case it will be 0). 


DbfCount Count the number of DBF records 
BX The DBF handle. 

RETURN: 
AX The number of records of the current type. 


PANIC: None 


Returns the number of records in the file of the current type. It will not alter the current record number. 


©DbfFindReadField Find a DBF record by field 


AL The number of fields to search. 

BX The DBF handle. 

cx The length of the buffer to match. 

DL The maximum field length to match with. 

DH The type and direction of the search. 

DI State. 

SI Pointer to the match buffer. 

DatEClassPtr The starting field from which to search (0 for first field) 
RETURN: = Carry clear 

AX The length of the record read. 

DI State. 

SI The offset in the main buffer of the record read. 
RETURN: Carry set 

EofErr No matching record was found. 
PANIC: 

PanicDbfl BX is not a valid DBF handle. 

PanicDbf£2 Parameters are invalid. 


Matches the given wild-card string with the string components of the specified fields in each record 
starting at the current record. If the current record is the end of file record, FofErr will be returned 
unless DH specifies pbfFindBackwards. 


This service is the same as DbfFindRead except that DatEClassPtr specifies the starting field from which 
the search starts (with 0 specifying the first field). For example, to search only the third, fourth and fifth 
text fields, set patEClassPtr to 2 and AL to 3. 


20 - 13 


20 - 14 


CHAPTER 21 


HARDWARE MANAGEMENT 


HwComboOn Switch on the combo 


None 
RETURN: None 
PANIC: None 
This service will switch on the combo hardware subsystem (CHS) if not already switched on. 
Although the CHS has been enabled, it can be accessed either by an external expansion device or by 
Asicl. If it is desired to access the CHS using Asicl then the SLDTX bit in the Asic! Control register 


needs to be enabled as well. Before turning the CHS on, it is important to see if it is available for use by 
calling the HwGet Combo service. 


This service is equivalent to HwComboOnInput for all variants except Asic9 variants (Series 3a). On Asic9 
variants HwComboOn puts the codec into output mode, while HwcComboonInput puts it into input mode. 


HwComboOftf Switch off the combo 


None 
RETURN: None 
PANIC: None 


This service will switch off the combo hardware subsystem (CHS) if not already switched off. 


HwPacksOn Switch on the SSDs 


None 
RETURN: None 
PANIC: None 
This service will switch on the SSD subsystem (SSDS) if not already switched on. 


This service is provided for the built in SSD drivers and should not be called by any other drivers or 
applications. 


HwPacksOff Switch off the SSDs 


None 
RETURN: None 
PANIC: None 
This service will switch off the SSD subsystem (SSDS) if not already switched off. 


This service is provided for the built in SSD drivers and should not be called by any other drivers or 
applications. 


21-1 


EPOC O/S SYSTEM SERVICES 


HwSetA2Control1Bits Set bits Asic2 register 1 


AL Mask of bits to be set. 
RETURN: None 
PANIC: None 


This service can be used to set bits in Asic2 control register 1. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit which is set in the mask will cause the corresponding bit in the control register to be set. 


HwClearA2Control1 Bits Clear bits Asic2 register 1 


AL Mask of bits to be cleared. 
RETURN: None 
PANIC: None 


This service can be used to clear bits in Asic2 control register 1. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit which is set in the mask will cause the corresponding bit in the control register to be cleared. 


HwReadA2Control1 Read Asic2 register 1 


None 
RETURN: 

AL The value currently in control register 1. 
PANIC: None 


This service can be used to read Asic2 control register 1. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it returns the value in its up-to-date copy. 


HwWriteA2Control1 Write Asic2 register 1 


AL The new value to be written to control register 1. 
RETURN: None 
PANIC: None 


This service can be used to write to Asic2 control register 1. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. 


HwSetA2Control2Bits Set bits Asic2 register 2 


AL Mask of bits to be set. 
RETURN: None 
PANIC: None 


This service can be used to set bits in Asic2 control register 2. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit set in the mask will cause the corresponding bit in the control register to be set. 


21-2 


21 HARDWARE MANAGEMENT 


HwClearA2Control2Bits Clear bits Asic2 register 2 


AL Mask of bits to be cleared. 
RETURN: None 
PANIC: None 


This service can be used to clear bits in Asic2 control register 2. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit set in the mask will cause the corresponding bit in the control register to be cleared. 


HwReadA2Control2 Read Asic2 register 2 


None 
RETURN: 

AL The value currently in control register 2. 
PANIC: None 


This service can be used to read Asic2 control register 2. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it returns the value in its up-to-date copy. 


HwWriteA2Control2 Write Asic2 register 2 


AL The new value to be written to control register 2. 
RETURN: None 
PANIC: None 


This service can be used to write to Asic2 control register 2. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. 


HwSetA2Control3Bits Set bits Asic2 register 3 


AL Mask of bits to be set. 
RETURN: None 
PANIC: None 


This service can be used to set bits in Asic2 control register 3. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit set in the mask will cause the corresponding bit in the control register to be set. 


HwClearA2Control3Bits Clear bits Asic2 register 3 


AL Mask of bits to be cleared. 
RETURN: None 
PANIC: None 


This service can be used to clear bits in Asic2 control register 3. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Each bit set in the mask will cause the corresponding bit in the control register to be cleared. 


21-3 


EPOC O/S SYSTEM SERVICES 


HwReadA2Control3 Read Asic2 register 3 


None 
RETURN: 

AL The value currently in control register 3. 
PANIC: None 


This service can be used to read Asic2 control register 3. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it returns the value in its up-to-date copy. 


HwWriteA2Control3 Write Asic2 register 3 


AL The new value to be written to control register 3. 
RETURN: None 
PANIC: None 


This service can be used to write to Asic2 control register 3. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. 


HwSelectChannel Select a serial channel 
AL The new channel to be selected. 

RETURN: 
AL The channel that was previously selected. 


PANIC: None 
This service will select which channel the serial controller in Asic2 will be connected to for subsequent 
serial data transfers. 


This service is necessary because the operating system cannot read directly from Asic2 and must keep its 
own up-to-date copy of the register contents. 


Interrupt service routines which use the serial controller must re-select the channel that was previously 
selected. This can be achieved by saving the value returned in AL when this service is called, as it is the 
currently selected channel. 


HwNullFrame Send a serial null frame 


None 
RETURN: None 
PANIC: None 


This service is useful for sending a null frame to a serial channel. This is important in order to guarantee 
that the controller and the slave device attached to the channel are synchronised. 


HwSwitchOff Switch off 


cx The number of quarter seconds to switch off for. 
RETURN: None 
PANIC: None 


This service may be called to switch off the machine. In fact, the machine is never truly switched off and 
can wake up again in order to service an event in the future. The value in CX determines how many 
quarters of a second must pass before the machine will wake up again. If the value in CX is less than or 
equal to 8 then this service will do nothing. 


21-4 


21 HARDWARE MANAGEMENT 


If an absolute timer is pending or a process is sleeping until an absolute time then the value in CX will be 
adjusted to make sure that the machine wakes up in time to service the outstanding timer or to wake up 
the process. 


If the value in CX is OxFFFF then the machine will just switch off until an outstanding absolute time 
event is ready to expire or until the user switches on the machine. 


The IBM PC version of EPOC does not support this service; instead, the HwExit service can be called 
which will return to DOS. 


HwExit Exit to DOS 


None 
RETURN: None 
PANIC: None 


This service is only available on the IBM PC version of Epoc/Os and will exit from the operating system 
and return to DOS. 


HwGetCombo Capture the combo subsystem 


None 
RETURN: = Carry clear 
Success 
RETURN: Carry set 
InUseErr The combo subsystem is already captured. 
PANIC: None 
This service acts as a gate to the combo subsystem so that two device drivers do not both try to access the 


combo subsystem at the same time. 


After capturing the combo subsystem, it must be released by calling the Hwrreecombo service when no 
longer required 


HwFreeCombo Free the combo subsystem 


None 
RETURN: None 
PANIC: None 


This service will free the combo subsystem after it has been captured with the HwGet combo service. 


HwGetChannel Get a channel 


AL The mask of the channels being captured. 
RETURN: Carry clear 
Success. 
RETURN: = Carry set 
InUseErr The channel is already captured. 
PANIC: None 
This service provides a gate to control access to the hardware interrupt service routines. 


It is also a handy way of ensuring that two device drivers do not start talking to the same expansion port at 
the same time, by getting the channel which is associated with that expansion port. 


The strategy is to request the channel before trying to talk to the hardware. If the channel is allocated 
successfully, then all is well and the driver can then talk to the expansion port. Whenever a driver has 
captured a channel in this way it must free the channel when it is no longer required by calling the 
HwFreeChannel Service. 


21-5 


EPOC O/S SYSTEM SERVICES 


HwFreeChannel Free a channel 


AL The mask of the channels being freed. 
RETURN: None 
PANIC: None 


This service will free a channel after it has been captured with the HwGetChannel service. 


HwGetPsuType Get the power supply type 


None 
RETURN: 

AL The power supply type. 
PANIC: None 


There are two power supply variants in the MC range of computers which use the EPOC operating 
system. Consequently there are two version of the operating system due to the different power supply 
handling code. Apart from this service, EPOC hides the differences between the two power supplies. The 
REPRO software which will load a new operating system into the FLASH memory uses this service to 
know which version of EPOC to load. 


HwGetSupplyStatus Get supplies status 


SS:BX Pointer to a SupplyEnt structure. 
RETURN: None 
PANIC: None 
This service may be used to get the current status of the various supplies. 


The value returned for the main battery and lithium batteries are in millivolts. The MainsPresent field 
can be: 


<0 mains status cannot be determined at the current 
time (if the SSD doors are open) 


0 mains is not present 
1 mains is present 
HwSupplyWarnings Get supplies warnings 
SS:BX Pointer to a SupplyWarningsEnt Structure. 


RETURN: None 
PANIC: None 


This service may be used to ask the operating system what the maximum value of the main and lithium 
battery reading can be and what an appropriate warning level would be. The values in the structures are in 
the same units as for the HwGet SupplyStatus, 1.e. millivolts. 


This service will return different values depending on the battery type set with the censetBatteryType 
service. If no battery type is set then the values for an alkaline battery will be returned. 


HwLcdContrastDelta Change the LCD contrast 


AL +ve to step contrast up. 
-ve to step contrast down. 
RETURN: None 
PANIC: None 


This service can be used to step the LCD contrast up or down depending on whether AL is positive or 
negative. 


21-6 


21 HARDWARE MANAGEMENT 


HwReadLcdContrast Get current LCD contrast 


None 
RETURN: 

AL The current contrast value. 
PANIC: None 


This service can be used to get the current contrast setting. 


HwSetBackLight Set backlight control 


BX The new backlight control value. 
RETURN: None 
PANIC: None 
This service can be used to set the backlight control. 


The value in BX contains two values. The bottom 15 bits are a time-out in ticks (1/32nd of a second) to 
switch off the backlight. If this value is zero then the backlight is not switched off automatically. 


The top bit (i.e. the sign bit), is used to enable/disable the operating system from toggling the backlight 
state on reception of the backlight key. Setting the bit will disable the operating system. 


HwGetBackLight Get backlight control 


None 
RETURN: 

AX The backlight control value. 
PANIC: None 


This service can be used to get the current backlight control value. 


HwBackLight Operate the backlight 


AL 0 - Switch off the backlight. 
1 - Switch on the backlight. 
2 - Toggle the backlight. 
3 - Return the backlight state. 
RETURN: Carry clear 
AL The previous or current backlight state: 
0 - backlight is/was off. 
1 - backlight is/was on. 
RETURN: Carry set 
Not SupportedErr Machine does not support a backlight. 
PANIC: None 


This service can be used to perform the following functions: 
e Switch the backlight on and off. 
e =6Toggle the backlight state. 
e Query the current backlight state. 


A backlit version of the machine can be determined by checking for the Not supportErr being returned 
with AL = 3 to query the backlight state. 


21-7 


EPOC O/S SYSTEM SERVICES 


©HwGetScanCodes Scan the state of all keys 


BX Pointer to 10 word array to take the scan codes. 
RETURN: Nothing. 
PANIC: None 


Writes values to the array at BX corresponding to the state of each key on the keyboard and to each 
application button. A unique bit is set for each key being pressed when this service is called. If the key is 
up then no bit is set. 


On the Series 3a, eleven bits are valid in each of the first eight words and the Workabout uses nine bits in 
each of the first eight words. On HC machines, eight bits in ten words are valid. This service is not 
available on the MC400, MC200 and Series 3. 


The set of scan codes is different for each machine's keyboard layout, but is fully determined by the 
position of the key on each type of machine. 


The following diagrams specify the scan code associated with each key on the different machines which 
support this service. Each box represents a key. The first number in each box gives the element of the 
array at BX used for that key (first element 0), and the second number gives the hexadecimal mask 
which, when anped with that array element, gives a non-zero result if that key is down. For example, on a 
Series 3a if the Control key is being pressed, element 2 of the array anped with hex 80 is non-zero. 


Series 3a keyboard 


HC alphabetic keyboard 


0,080 6,040 7,040 


Note that the scan code (0, 080) given for the On/Off key is that for Off. The scan codes for On 
(8,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. 


21-8 


21 HARDWARE MANAGEMENT 


The Off scan code is received if the application captures the Off key (capture of this key by the HC 
Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide) 


HC numeric keyboard 


0,080 6,040 7,040 


0,020 3,001 3,002 3,004 3,008 0,010 
6,020 1,004 1,008 1,010 5,002 6,002 


5,001 0,040 0,004 0,008 
5,010 5,008 5,004 7,002 
0,001 


Note that the scan code given for the On/Off key (0, 080) is that for Off. The scan codes for On 

(g,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. 
The Off scan code is received if the application captures the Off key (capture of this key by the HC 
Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide). 


Workabout keyboard 


C= 


3,040 4,040 5,040] |6,040 oa 
6.020 7,020 0,040 1,040 eS 
2,020 3,020 4,020 5,020 
6,010 7,010 0,020 1,020 
2,010 3,010 4,010 5,010 
(— 
6, 008 7,008 0,010 1,010 
NG 
0,00 1,00 2,00 3,00 4,00 5,00 
2,004 3,004 4,004 5,004 6,004 7,004 
4,004 5,002 6, 002 7,002 0,004 1,004 
0,00] 1,004 0,004 1,004 2,002 3,002 
( > 
2,001 4,00] 5,00] 
S S 
(— ay 
3,001 6,00] 7,00] 
X S 


21-9 


EPOC O/S SYSTEM SERVICES 


Note that the scan code given for the On/Esc key (0,100) is the Escape scan code. The scan codes for On 
(0, 080 - not shown in the above diagram) and Off (6, 020) are not normally received by application code. 
The Off scan code is received if the application captures the Off key. 


©HwComboOninput Switch on the combo in input mode 


None 
RETURN: None 
PANIC: None 


This service is equivalent to HwComboon for all variants except Asic9 variants (Series 3a). On Asic9 
variants HwComboon turns on the codec and puts it into output mode. HwcomboOnInput also turns on the 
codec but puts it into input mode. 


©HwSupplyinfo Get additional power supply data 


BX Pointer to supplyInfokEnt structure 
RETURN: Nothing. 
PANIC: None. 


Write information concerning the various power supplies to the supplyInfokEnt structure at BX. This 
information can be used to monitor battery and mains usage. Only Asic9 variants (Series 3a) return 
meaningful data. 


The supplyInfoknt structure is defined in epocsibo.inc. 


Hardware Management update 


The majority of the additional EPOC hardware management system services described in this section were 
introduced for the Series 3c and Siena. 


With the exception of the HC, all the services are, in principle, available on any machine that contains 
EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in 
this section should generate an =_GEN_NsuP error. 


Some services require the presence of hardware that is not built into all machines in the SIBO range. If 
the relevant hardware is not present on a particular machine, calling the service will either have no effect 
or return an error of —_GEN_Nnsup. The descriptions of such services contain a list of the machines on 
which they are intended to be used. 


HwResetBatteryStatus Reset the battery status 


None 
RETURN: None 
PANIC: None 


Reset the battery status information. This service has the same effect as replacing the main batteries. 


HwEnableAutoBatReset Enable/disable battery info reset 
BX Enable/disable/query the status 

RETURN: 
AL The current auto battery reset status, if queried, otherwise none. 


PANIC: None 


This service is primarily intended for use on the Workabout. 
Enable or disable an auto reset of the battery information when the battery is recharged in-place. 
The value of BX should be 1 to enable, 0 to disable, or -1 to query the auto reset status. 


If querying the status, a value of lor 0 is returned in AX, respectively meaning that auto reset is enabled 
or disabled. 


21-10 


21 HARDWARE MANAGEMENT 


HwGetBatData Return battery information 
None 

RETURN: 
AX Pointer to battery information. 


PANIC: None 


Return the address of the supplyInfoEnt battery information structure in the OS data segment. 
The structure is defined as: 


SupplyInfoEnt struc 


SuMainBat Level db ? 
SuMainBatStatus db ? 
SuBackupBatLevel db ? 
SuDcLevel db ? 
SuWarningFlags dw ? 
SuInsertionDate dd 2 
SuTicksInUseBattery dd ? 
SuTicksInUseDc dd ? 
SuMilliampTicks dd ? 


SupplyInfoEnt ends 


This structure is equivalent to the PLIB &_suppLy_inro struct. 


HwReLogPacks Relog the SSDs 


None 


RETURN: = Carry clear 


Success 
RETURN: = Carry set 
AL Error number 


PANIC: None 


Relog the packs. This service has the same effect as opening and then closing the pack doors on a 
Series 3a. 


This service is supplied for internal use and is not intended to be called by application code. 


HwSetiRPowerLevel Set the IR power level 
BX Required power level 

RETURN: 
AX The previous IR power level 


PANIC: None 


This service is only available on Series 3c and Siena machines. 
Set the power level used to drive the IR device to be high or low. 
BX should be passed as | to set the high power level, or 0 to set the low power level. 


Return a value (0 for low and 1 for high) representing the IR power level as it was before the service was 
called. 


HwReturnTickCount Sense the current tick count 


None 
RETURN: 

AX Tick count. 
PANIC: None 


Return, in AX, a value that is incremented on every tick (32 times per second). 


21-11 


EPOC O/S SYSTEM SERVICES 


HwReturnExpansionPortState Sense the expansion port state 


None 

RETURN: 
AX Expansion port state. 
BX At present, always zero. 


PANIC: None 


Return the type and current state of the expansion port: 


The value of AL is non-zero if the pack doors are open. Additionally, on Series 3c machines, it is non zero 
for a short period after something is plugged into, or removed from, the Honda connector. 


AH contains one of the following values in its lower three bits: 


0x00 Expansion port is Series 3/ Series 3a 6-pin 
0x01 Expansion port is Workabout LIF 

0x02 Expansion port is Siena Honda 

0x03 Expansion port is Series 3c Honda 

0x04 Expansion port is HC 


In addition, the following value may be ored into AH: 


0x80 The machine contains the Condor chip 


HwExpansionOn Enable power to Honda connector 


None 
RETURN: None 
PANIC: None 


This service is only available on Series 3c machines. 
Enable the supply of power to a peripheral device connected to the machine via the Honda connector. 


This service is provided for the built-in SSD drivers and should not be called by any other drivers or 
applications. 


HwExpansionOff Disable power to Honda connector 


None 
RETURN: None 
PANIC: None 


This service is only available on Series 3c machines. 
Disable the supply of power to a peripheral device connected to the machine via the Honda connector. 


This service is provided for the built-in SSD drivers and should not be called by any other drivers or 
applications. 


21-12 


APPENDIX A 


INTERRUPT AND FUNCTION NUMBERS 


Introduction 


Epoc system services are invoked using the INT nn 8086 instruction. There are two types of system 
services. 


e Single - which just do one function. 
e = Multi - which do more than one function. 


The multi service functions also require the AH register to be loaded with a value which selects the actual 
function to be performed. 


The following section lists the actual numbers associated with the system services and their function 
numbers. In the listings, names starting with Nm are function numbers and should be placed in AH. All 
names starting with Nm are made up of Nm followed by a number of name components. The first 
component after Nm is the name of the interrupt to invoke. For example: 


NmFilOpen, where Fil is the first name component uses FilManager. 


NmHeapFreeCell, where Heap is the first name component uses HeapManager. NmDbfClose, where Dbf 
is the first name component uses DbfManager. 


MOV AH, NmFilOpen 
INT FilManager 


All names not starting with Nm are the names of the single and multi level interrupts. 


In the documentation, functions are referred to by the name with the leading Nm missing. Thus SegOpen 
can be called as follows: 


MOV AH, NmSegOpen 
INT SegManager 


Single service interrupts are just referred to by their names. Thus StringLength is called as follows: 
INT StringLength 
As usual there are a few exceptions to this rule: 


e NmLongUnsignedIntRandom is under INT GenManager. NmloOpen is under INT DevManager. 


EPOC O/S SYSTEM SERVICES 


Alphabetical list of functions 


CONVMANAGER 


NMCONVARGUMENTSTOBUFFER 


NMCONVFLOATTOBUFFER 


NMCONVINTI 


TOBUFFER 


NMCONVLONGINI 


NMCONVSTRI 


NMCONVSTRI 


NMCONVSTRI 


NMCONVSTRI 


NMCONVSTRI 


NMCONVUNSI 


NG1 


NG1 


NG1 


NG1 


[TTOBUFFER 


TOF LOAT 


TOINT 


TOLONGINT 


TOUNSIGNEDINT 


NG1 


TOUNS IGNEDLONGINT 


GNEDINTTOBUFFER 


NMCONVUNSI 


DBFMANAGER 


GNEDLONGINTTOBUFFER 


NMDBFABSREAD 


NMDBFABSREADSENSE 


NMDBFAPPEND 


NMDBFBACKREAD 


NMDBFCLOSE 


NMDBFCOMPRESS 


NMDBFCOP YDOWN 


NMDBFCOPYFILE 


NMDBF COUNT 


NMDBFDESCRECORDREAD 


NMDBFDESCRECORDWRITE 


NMDBFERASEREAD 


NMDBFEXTHEADERREAD 


NMDBFEXTHEADERWRITE 


NMDBFFILESIZE 


NMDBFF INDREAD 


NMDBFF INDREADFIELD 


NMDBFFIRSTREAD 


NMDBFF LUSH 


NMDBFLASTREAD 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


OO8AH 


0004H 


0009H 


0002H 


0003H 


OOOAH 


0007H 


0008H 


0005H 


OO06H 


OOOOH 


0001H 


OOD8H 


NM 


NM 


NM 


NM 


NM 


NM 


DBFNEXTREAD 


DBFOPEN 


DBFSENSE 


DBF TRASH 


DBFUPDATE 


DBFVERSION 


DEVMANAGER 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


DEVDELETE 


DEVF IND 


DEVGETPDDADDRESS 


DEVHOLD 


DEVINSTALL 


DEVLOADLDD 


DEVLOADPDD 


DEVOPENPDD 


DEVQUERYUNITS 


DEVREMOVE 


DEVRESUME 


DEVVECTOR 


IOOPEN 


FILMANAGER 


NMF ILCHANGEDIRECTORY 


NMF ILCONNECT 


NMF ILDELETE 


NMF ILEXECUTE 


NMF ILLOCCHANGED 


NMF ILLOCDEVICE 


NMF ILLOCREADPDD 


NMF ILMAKEDIRECTORY 


NMF ILOPENUNIQUE 


NMF ILPARSE 


NMF ILPATHGET 


NMF ILPATHGETBYID 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


OOODH 


0000H 


0015H 


0003H 


0013H 


OOOAH 


0085H 


0087H 


EPOC O/S SYSTEM SERVICES 


NMF ILPATHSET 


NMFILPATHTEST 


NMF I LRENAME 


NMFILSETFILEDATE 


NMFILSETINITIALPATH 


NMFILSTATUSDEVICE 


NMFILSTATUSGET 


NMFILSTATUSSET 


NMFILSTATUSSYSTEM 


NMFILSYSTEMATTACH 


NMFILSYSTEMDETACH 


FLOATMANAGER 


NMFLOATACOS 


NMF LOATASIN 


NMF LOATATAN 


NMFLOATCOS 


NMF LOATEXP 


NMF LOATINT 


NMF LOATLN 


NMF LOATLOG 


NMF LOATMOD 


NMF LOATPOW 


NMF LOATRAND 


NMFLOATSIN 


NMF LOATSQRT 


NMF LOATTAN 


GENMANAGER 


NMGENALARMHOOK 


NMGENALARMID 


NMGENALARMUNHOOK 


NMGENCRC 


NMGENDEFERREDMODE 


NMGENENVBUFFERDELETE 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


0004 


0005H 


0007 


0013H 


0012H 


OO0A 


0008 


0009H 


OOOBH 


OOOE 


OOOFH 


008C 


oO 

fo} 

fo} 

as 
r 


oO 

oO 

oO 

Ww 
r 


fo} 

fo} 

oO 

ray 
r 


Le 

fo} 

oO 

oO) 
r 


fo} 

fo} 

fo} 

~ 
r 


oO 

fo} 

oa 

foo) 
r 


fo) 
fo) 
fo) 
aa 
" 


0O8BH 


002BH 


002DH 


002CH 


0029H 


0008H 


0023H 


NMGENENVBUFFERF IND 


NMGENENVBUFFERGET 


NMGENENVBUFFERSET 


NMGENENVSTRINGDELETE 


NMGENENVSTRINGF IND 


NMGENENVSTRINGGET 


NMGENENVSTRINGSET 


NMGENGETAMPMTEXT 


NMGENGETAUTOMAINS 


NMGENGETAUTOSWITCHOFF VALUE 


NMGENGETBATTERYTYPE 


NMGENGETCOMMANDLINE 


NMGENGETCOUNTRYDATA 


NMGENGETERRORTEXT 


NMGENGETLANGUAGECODE 


NMGENGETNOTIFYSTATE 


NMGENGETOSDATA 


NMGENGETRAMSIZEINPARAS 


NMGENGETSOUNDFLAGS 


NMGENGETSUFFIXES 


NMGENGETTEXT 


NMGENLCDTYPE 


NMGENMARKACTIVE 


NMGENMARKNONACTIVE 


NMGENMASKDECRYPT 


NMGENMASKENCRYPT 


NMGENMASKINIT 


NMGENNOTIFY 


NMGENNOTIFYERROR 


NMGENNOTIFYHOOK 


NMGENNOTIFYUNHOOK 


NMGENPARSE 


NMGENPASSWORDCONTROL 


NMGENPASSWORDQUERY 


NMGENPASSWORDSET 


NMGENPASSWORDTEST 


NMGENRESETREVECTOR 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


EPOC O/S SYSTEM SERVICES 


NMGENROMVERS ION 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


NMGENSET 


TAUTOMAINS 


TAUTOSWITCHOFF VALUE 


[TBATTERYTYPE 


[CONFIG 


TCOUNTRYDATA 


[NOTIFYSTATE 


TONEVENTS 


TREVECTOR 


TSOUNDF LAGS 


NMGENSOUND 


NMGENSTARTREASON 


NMGENTICKLE 


NMGENVERSION 


NMLONGUNSIGNEDINTRANDOM 


HEAPMANAGER 


NMHEAPADJUSTCELLSIZE 


NMHEAPALLOCATECELL 


NMHEAPCELLSIZE 


NMHEAPFREECELL 


NMHEAPFREEMEMORY 


NMHEAPREALLOCATECELL 


NMHEAPSETGRANULARITY 


HWMANAGER 


NMHWBACKLIGHT 


NMHWCLEARA2CONTROLIBITS 


NMHWCLEARA2CONTROL2BITS 


NMHWCLEARA2CONTROL3BITS 


NMHWCOMBOOFF 


NMHWCOMBOON 


NMHWCOMBOONINPUT 


NMHWEXIT 


NMHWFORCESUPPLYREADING 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


0081 


OO8E 


0020 


0005 


0009 


000D 


0001 


0000 


0021 


0016 


001D 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


H 


WFREECHANNEL 


WFREECOMBO 


WGETBACKLIGHT 


WGETCHANNEL 


WGETCOMBO 


WGETPSUTYPE 


WGETSCANCODES 


WGETSUPPLYSTATUS 


WLCDCONTRASTDELTA 


WNULLFRAME 


WPACKSOFF 


WPACKSON 


WREADA2CONTROL1 


WREADA2CONTROL2 


WREADA2CONTROL3 


WREADLCDCONTRAST 


WSELECTCHANNEL 


WSETA2CONTROLIBITS 


WSETA2CONTROL2BITS 


WSETA2CONTROL3BITS 


WSETBACKLIGHT 


WSUPPLYINFO 


WSUPPLYWARNINGS 


WSWITCHOFF 


WWRITEA2CONTROL1 


WWRITEA2CONTROL2 


WWRITEA2CONTROL3 


IOMANAGER 


NM] 


NM] 


NM 


NM] 


NMI 


NM 


NMI 


OADDAPPLICATIONHANDLER 


OADDHANDLER 


IOASYNCHRONOUS 


OASYNCHRONOUSNOERROR 


OCLOSE 


IOENABLEAPPLICATIONHANDLER 


OENABLEHANDLER 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


OO1A 


0018 


0086 


0015 


000B 


0000 


0001 


0010 


0017 


000D 


EPOC O/S SYSTEM SERVICES 


NMI 


NMI 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NMI] 


NM] 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


OKEYANDMO 


OKEYANDMO 


ONEXTHALF 


OPLAYSOUN 


OPLAYSOUN 


OPLAYSOUN 


OREAD 


ORECORDSO 


ORECORDSO 


ORECORDSO 


OREMOVEAPPLICATIONHANDLER 


USEASYNCHRONOUS 


USEWITHWAIT 


SECOND 


DA 


DCANCEL 


DW 


UNDA 


UNDCANCEL 


UNDW 


OREMOVEHANDLER 


OREQUESTRESET 


OREQUESTRESETCANCEL 


OROOT 


OSEEK 


OSHIFTSTATES 


OSIGNAL 


OSIGNALBYPID 


OSIGNALBYP IDNORESCHED 


OSIGNALKILLASYNCHRONOUS 


OSIGNALKILLCANCEL 


OSUPER 


OWAITFORS 


OWAITFORS 


IGNAL 


IGNALNOHANDLER 


OWAITFORSTATUS 


OWITHWAIT 


OWRITE 


OYIELD 


IOSERMANAGER 


NM] 


NM] 


NM] 


NM] 


NM] 


OSERADDHANDLER 


OSERATTACHONOPENCHAN 


OSERCANCELALLSIGNALUSER 


OSERCANCELIOREQUEST 


OSERCHECKREADSI 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


001C 


0014 


OODE 


0001 


0O00D 


0O01C 


001B 


0011 


NM] 


NM] 


NM 


NM] 


NM] 


NM 


NM] 


NM] 


NM 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


OSERCHECKWRITESI 


OSERCLOSETIMERHANDLER 


IOSERDETACHFREE 


OSERFREE 


OSERHANDLERSAVEERROR 


IOSERONOPENCHAN 


OSEROPEN 


OSEROPENHANDLER 


IOSEROPENT IMERHANDLER 


OSERQUEUEREAD 


OSERQUEUESUPER 


OSERQUEUETIMER 


OSERQUEUEWRITE 


OSERREMOVEHANDLER 


OSERSENSEONOPENCHAN 


OSERSETHANDLER 


OSERSIGNALCOMPLETE 


OSERS IGNALCOMP LETEOK 


OSERSIGNALUSER 


OSERS IGNALUSERREAD 


OSERS IGNALUSERREADOK 


OSERSIGNALUSERWRITE 


OSERSIGNALUSERWRITEOK 


OSERSYNCWRITE 


OSERTIMERCANCEL 


OSERTIMERCLOSE 


OSERTIMEROPEN 


LIBMANAGER 


NMLI 


NMLI 


NMLI 


NMLI 


BCOPY 


BCREATE 


IBCREATEBYHANDLE 


IBDESTROY 


IBFIND 


BHANDLE 


BLINK 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


0084 


0008 


0005 


0006 


0007 


0003 


0004 


0002 


EPOC O/S SYSTEM SERVICES 


NMLIBLOAD EQU OOOOH 
NMLIBLOADFILE EQU OOOAH 
NMLIBOPEN EQU 0009H 
NMLIBRECLASS EQU OOOBH 
NMLIBRECLASSBYHANDLE EQU OOOCH 
NMLIBUNLOAD EQU 0001H 
MES SMANAGER EQU 0083H 
NMMESSFREE EQU 0007H 
NMMESSINIT EQU OOOOH 
NMMESSRECEIVEAS YNCHRONOUS EQU 0001H 
NMMESSRECEIVECANCEL EQU 0003H 
NMMESSRECEIVEWITHWAIT EQU 0002H 
NMMESSSEND EQU 0004H 
NMMESSSENDRECEIVEAS YNCHRONOUS EQU 0005H 
NMMESSSENDRECEIVEWITHWAIT EQU OO006H 
NMMESSSIGNAL EQU 0008H 
NMMESSSIGNALCANCEL EQU 0009H 
NMMESSSIGNALCANCELX EQU OOOAH 
PROCMANAGER EQU 0088H 
NMP ROCCREATE EQU 0004H 
NMPROCCREATETASK EQU 0005H 
NMPROCF IND EQU OOOBH 
NMP ROCGETOWNER EQU 0010H 
NMPROCGETPRIORITY EQU 0002H 
NMPROCID EQU OOOOH 
NMPROCIDBYNAME EQU 0001H 
NMPROCKILL EQU 0008H 
NMP ROCNAMEBY ID EQU OOOAH 
NMPROCONTERMINATE EQU OOOEH 
NMPROCPANICBYID EQU 0009H 
NMP ROCRENAME EQU OOOCH 
NMP ROCRESUME EQU OO006H 
NMPROCSETPRIORITY EQU 0003H 


A-10 


A INTERRUPT AND FUNCTION NUMBERS 


NMP ROCSUSPEND EQU OOO07H 
NMPROCTERMINATE EQU OOODH 
NMPROCWATCHALLEXITS EQU OOOFH 
SEGMANAGER EQU 0080H 
NMSEGADJUSTSIZE EQU OO006H 
NMSEGCLOSE EQU 0004H 
NMSEGCLOSELOCKEDORDEVICE EQU OOODH 
NMSEGCOP YFROM EQU 0009H 
NMSEGCOPYTO EQU 0008H 
NMSEGCREATE EQU 0001H 
NMSEGDELETE EQU 0002H 
NMSEGF IND EQU OO007H 
NMSEGFREEMEMORY EQU OOOOH 
NMSEGLOCK EQU OOOAH 
NMSEGOPEN EQU 0003H 
NMSEGRAMDISKUSED EQU OOOCH 
NMSEGSIZE EQU 0005H 
NMSEGUNLOCK EQU OOOBH 
SEMMANAGER EQU 0082H 
NMSEMCREATE EQU OO00H 
NMSEMDELETE EQU 0001H 
NMSEMS IGNALMANY EQU 0004H 
NMSEMSIGNALONCE EQU 0003H 
NMSEMS IGNALONCENORESCHED EQU 0005H 
NMSEMWAIT EQU 0002H 
TIMMANAGER EQU 0089H 
NMTIMDATETODAYSECONDS EQU 0007H 
NMT IMDAYOFWEEK EQU 0009H 
NMTIMDAYSECONDSTODATE EQU OO06H 
NMTIMDAYSECONDSTOSYSTEMTIME EQU 0005H 
NMTIMDAYSINMONTH EQU 0008H 


EPOC O/S SYSTEM SERVICES 


w 


w 


w 


w 


w 


w 


NMTIMGETSYSTEMTIME 


NMT IMNAMEOFDAY 


NMT IMNAMEOFDAYABB 


NMT IMNAMEOFMONTH 


NMT IMNAMEOFMONTHABB 


NMTIMSETSYSTEMTIME 


NMTIMSLEEPFORTENTHS 


NMTIMSLEEPFORTICKS 


NMTIMSYSTEMT IMETODAY SECONDS 


NMTIMWAITABSOLUTE 


NMT IMWEEKNUMBER 


UFFERCOMPARE 


UFFERCOMPAREFOLDED 


UFFERCOPY 


UFFERJUSTIFY 


UFFERLOCATE 


UFFERLOCATEFOLDED 


UFFERMATCH 


UFFERMATCHFOLDED 


UFFERSUBBUFFER 


UFFERSUBBUFFERFOLDED 


UFFERSWAP 


HARISALPHABETIC 


HARISALPHANUMERIC 


HARISCONTROL 


HARISDIGIT 


HARISGRAPHIC 


HARISHEXDIGIT 


HARISLOWERCASE 


HARISPRINTABLE 


HARISPUNCTUATION 


HARISSPACE 


HARISUPPERCASE 


HARTOFOLDEDCHAR 


HARTOLOWERCHAR 


HARTOUPPERCHAR 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


DUMMY 


F LOATADD 


F LOATCOMPARE 


FLOATDIVIDE 


FLOATMULTIPLY 


FLOATNEGATE 


FLOATSUBTRACT 


FLOATTOINT 


F LOATTOLONG 


FLOATTOUNSIGNEDINT 


F LOATTOUNS IGNEDLONG 


GENDATASEGMENT 


GENINTBYNUMBER 


NTTOFLOAT 


OKEYANDMOUSESTATUS 


ONEXTHALFSECONDSTATUS 


LIBENTER 


LIBENTERSEND 


LIBLEAVE 


LIBSEND 


LIBSENDEXACT 


LIBSENDEXIT 


LIBSENDSUPER 


LONGINTCOMPARE 


LONGINTDIVIDE 


LONGINTMULTIPLY 


LONGTOF LOAT 


LONGUNS IGNEDINTCOMPARE 


LONGUNSIGNEDINTDIVIDE 


LONGUNSIGNEDINTMULTIPLY 


PROCCOPYFROMBYID 


PROCCOPYTOBYID 


PROCINDSTRINGCOPYFROMBYID 


PROCPANIC 


STRINGCAPITALISE 


STRINGCOMPARE 


STRINGCOMPAREFOLDED 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


OOCFH 


OOBBH 


OOBDH 


OOBCH 


OOCDH 


OOBEH 


OOCOH 


OOBFH 


0091H 


0092H 


OODCH 


0090H 


OODBH 


OOAFH 


OOBOH 


EPOC O/S SYSTEM SERVICES 


STRINGCONVERTTOFOLDED 


STRINGCOPY 


STRINGCOPYFOLDED 


STRINGLENGTH 


STRINGLOCATE 


STRINGLOCATEFOLDED 


STRINGLOCATEINREVERSE 


STRINGLOCATEINREVERSEFOLDED 


STRINGMATCH 


STRINGMATCHFOLDED 


STRINGSUBSTRING EQU 


STRINGSUBSTRINGFOLDED 


STRINGVALIDATENAME 


UNSIGNEDINTTOFLOAT 


UNSIGNEDLONGTOFLOAT 


WSERVFUNCTIONS EQU 


WSERVOPCODES 


Numerical list of functions 


SEGMANAGER 


NMSEGFREEMEMORY 
NMSEGCREATE 
NMSEGDELETE 
NMSEGOPEN 
NMSEGCLOSE 
NMSEGSIZE 
NMSEGADJUSTSIZE 
NMSEGF IND 
NMSEGCOPYTO 
NMSEGCOP YFROM 
NMSEGLOCK 
NMSEGUNLOCK 
NMSEGRAMDISKUSED 


NMSEGCLOSELOCKEDORDEVICE 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


D6H 


OOAEH 


OOACH 


OOADH 


OOB9H 


00B3H 


OOB4H 


OOB5H 


OOB6H 


0OB1H 


OOB2H 


OOB8H 


OOBAH 


OOCCH 


OOCEH 


008DH 


0080H 


0000H 


0001H 


0002H 


0003H 


0004H 


0005H 


OO06H 


OO0O07H 


0008H 


0009H 


OOOAH 


OOOBH 


OOOCH 


OOODH 


A INTERRUPT AND FUNCTION NUMBERS 


HEAPMANAGER EQU 0081H 
NMHEAPALLOCATECELL EQU OOOOH 
NMHEAPREALLOCATECELL EQU 0001H 
NMHEAPADJUSTCELLSIZE EQU 0002H 
NMHEAPFREECELL EQU 0003H 
NMHEAPCELLSIZE EQU 0004H 
NMHEAPSETGRANULARITY EQU 0005H 
NMHEAPFREEMEMORY EQU OO06H 

SEMMANAGER EQU 0082H 
NMSEMCREATE EQU OOOOH 
NMSEMDELETE EQU 0001H 
NMSEMWAIT EQU 0002H 
NMSEMS IGNALONCE EQU 0003H 
NMSEMS IGNALMANY EQU 0004H 
NMSEMS IGNALONCENORESCHED EQU 0005H 

MES SMANAGER EQU 0083H 
NMMESSINIT EQU OOOOH 
NMMESSRECEIVEASYNCHRONOUS EQU 0001H 
NMMESSRECEIVEWITHWAIT EQU 0002H 
NMMESSRECEIVECANCEL EQU 0003H 
NMMESSSEND EQU 0004H 
NMMESSSENDRECEIVEASYNCHRONOUS EQU 0005H 
NMMESSSENDRECEIVEWITHWAIT EQU OO06H 
NMMESSFREE EQU 0007H 
NMMESSSIGNAL EQU 0008H 
NMMESSSIGNALCANCEL EQU 0009H 
NMMESSSIGNALCANCELX EQU OOOAH 

LIBMANAGER EQU 0084H 
NMLIBLOAD EQU 0O00H 
NMLIBUNLOAD EQU 0001H 


EPOC O/S SYSTEM SERVICES 


NMLIBLINK 


NMLIBF IND 


NMLIBHANDLE 


NMLIBCREATE 


NMLIBCREATEBYHANDLE 


NMLIBDESTROY 


NMLIBCOPY 


NMLIBOPEN 


NMLIBLOADFILE 


NMLIBRECLASS 


NMLIBRECLASSBYHANDLE 


DEVMANAGER 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


IOOPEN 


DEVOPENPDD 


DEVGETPDDADDRESS 


DEVINSTALL 


DEVHOLD 


DEVRESUME 


DEVLOADLDD 


DEVLOADPDD 


DEVDELETE 


DEVQUERYUNITS 


DEVF IND 


DEVREMOVE 


DEVVECTOR 


IOMANAGER 


NM] 


NM] 


NM 


NM] 


NM] 


NM 


NMI 


A- 16 


OASYNCHRONOUS 


OASYNCHRONOUSNOERROR 


IOWITHWAIT 


OROOT 


OSUPER 


IOWAITFORSIGNAL 


OWAITFORSTATUS 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


0085H 


OO000H 


0001H 


0002H 


0003 


0004 


0005H 


0006 


0007 


0008H 


0009 


OO0A 


OOOBH 


000C 


0086H 


0000 


0001H 


0002H 


0003 


0004H 


0005 


0006 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NMI 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


NM] 


OYIELD 


OSIGNAL 


OSIGNALBYPID 


OSIGNALBYP IDNORESCHED 


OADDHANDLER 


OREMOVEHANDLER 


OENABLEHANDLER 


OREQUESTRESET 


OREQUESTRESETCANCEL 


OCLOSE 


OREAD 


OWRITE 


OSEEK 


OKEYANDMOUSEWITHWAIT 


OADDAPPLICATIONHANDLER 


OREMOVEAPPLICATIONHANDLER 


OENABLEAPPLICATIONHANDLER 


OSHIFTSTATES 


OWAITFORS IGNALNOHANDLER 


OSIGNALKILLASYNCHRONOUS 


OSIGNALKILLCANCEL 


OKEYANDMOUSEAS YNCHRONOUS 


ONEXTHALF SECOND 


OPLAYSOUNDA 


OPLAYSOUNDW 


OPLAYSOUNDCANCEL 


ORECORDSOUNDA 


ORECORDSOUNDW 


ORECORDSOUNDCANCEL 


FILMANAGER 


NMF ILCONNECT 


NMF ILEXECUTE 


NMF ILPARSE 


NMF ILPATHGET 


NMF ILPATHSET 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


0087 


0000 


0001 


0002 


0003 


0004 


EPOC O/S SYSTEM SERVICES 


NMFILPATHTEST EQU 0005H 
NMF ILDELETE EQU OO006H 
NMF I LRENAME EQU O007H 
NMFILSTATUSGET EQU 0008H 
NMFILSTATUSSET EQU 0009H 
NMFILSTATUSDEVICE EQU OOOAH 
NMFILSTATUSSYSTEM EQU OOOBH 
NMF ILMAKEDIRECTORY EQU OOOCH 
NMF ILOPENUNIQUE EQU OOODH 
NMFILSYSTEMATTACH EQU OOOEH 
NMFILSYSTEMDETACH EQU OOOFH 
NMF ILPATHGETBYID EQU 0010H 
NMF ILCHANGEDIRECTORY EQU 0011H 
NMFILSETINITIALPATH EQU 0012H 
NMFILSETFILEDATE EQU 0013H 
NMF I LLOCCHANGED EQU 0014H 
NMF ILLOCDEVICE EQU 0015H 
NMF ILLOCREADPDD EQU 0016H 
PROCMANAGER EQU 0088H 
NMPROCID EQU 0O000H 
NMPROCIDBYNAME EQU 0001H 
NMPROCGETPRIORITY EQU 0002H 
NMPROCSETPRIORITY EQU 0003H 
NMP ROCCREATE EQU 0004H 
NMP ROCCREATETASK EQU 0005H 
NMP ROCRESUME EQU OO06H 
NMP ROCSUSPEND EQU OO007H 
NMPROCKILL EQU 0008H 
NMPROCPANICBYID EQU 0009H 
NMP ROCNAMEBY ID EQU OOOAH 
NMPROCF IND EQU OOOBH 
NMP ROCRENAME EQU OOOCH 
NMPROCTERMINATE EQU OOODH 
NMPROCONTERMINATE EQU OOOEH 
NMPROCWATCHALLEXITS EQU OOOFH 
NMP ROCGETOWNER EQU 0010H 


A-18 


TIMMANAGER 


NMTIMSLEEPFORTENTHS 


NMTIMSLEEPFORTICKS 


NMTIMGETSYSTEMT IME 


NMTIMSETSYSTEMTIME 


NMTIMSYSTEMT IMETODAY SECONDS 


NMTIMDAYSECONDS1 


NMTIMDAYSECONDS1 


TOSYSTEMTIME 


TODATE 


NMTIMDATETODAYSECONDS 


NMTIMDAYSINMONTH 


NMT IMDAYOFWEEK 


NMT IMNAMEOFDAY 


NMT IMNAMEOFMONTH 


NMTIMWAITABSOLUTE 


NMT IMWEEKNUMBER 


NMT IMNAMEOFDAYABB 


NMT IMNAMEOFMONTHABB 


CONVMANAGER 


NMCONVUNSIGNEDINTTOBUFFER 


NMCONVUNSIGNEDLONGINTTOBUFFER 


NMCONVINTTOBUFFER 


NMCONVLONGINTTOBUFFER 


NMCONVARGUMENTSTOBUFFER 


NMCONVSTRINGTOUNSIGNEDINT 


NMCONVSTRINGTOUNS IGNEDLONGINT 


NMCONVSTRINGTOINT 


NMCONVSTRINGTOLONGINT 


NMCONVFLOATTOBUFFER 


NMCONVSTRINGTOFLOAT 


GENMANAGER 


NMGENVERSION 


NMGENLCDTYPE 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


0089H 


0O000H 


0001H 


0002H 


0003H 


0004H 


0005H 


0006H 


OO007H 


0008H 


0009H 


OOOAH 


OOOBH 


O0O00CH 


OOODH 


OOOEH 


OOOFH 


OO8AH 


OO8BH 


0O000H 


0001H 


EPOC O/S SYSTEM SERVICES 


NMGENSTARTREASON 


NMGENPARSE 


NMLONGUNSIGNEDINTRANDOM 


NMGENGETCOUNTRYDATA 


NMGENGETERRORTEXT 


NMGENGETOSDATA 


NMGENDEFERREDMODE 


NMGENNOTIFY 


NMGENNOTIFYERROR 


NMGENNOTIFYHOOK 


NMGENNOTIFYUNHOOK 


NMGENGETRAMSIZEINPARAS 


NMGENGETCOMMANDLINE 


NMGENGETSOUNDFLAGS 


NMGENSETSOUNDFLAGS 


NMGENSOUND 


NMGENMARKACTIVE 


NMGENMARKNONACT!I 


NMGENGETTEXT 


NMGENGETNOTIFYS1 


NMGENSETNOTIFYS1 


NMGENGETAUTOSWIT 


NMGENSETAUTOSWIT 


NMGENSETREVECTOR 


VE 


TATE 


TATE 


[CHOFF VALUE 


[CHOFF VALUE 


NMGENRESETREVEC1 


TOR 


NMGENGETLANGUAGECODE 


NMGENGETSUFFIXES 


NMGENGETAMPMTEXT 


NMGENSETCOUNTRYDATA 


NMGENGETBATTERYTYPE 


NMGENSETBATTERYTYPE 


NMGENENVBUFFERGET 


NMGENENVBUFFERSET 


NMGENENVBUFFERDELETE 


NMGENENVBUFFERF IND 


NMGENENVSTRINGGET 


NMGENENVSTRINGSET 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


NMGENENVSTRINGDELETE EQU 0027H 
NMGENENVSTRINGF IND EQU 0028H 
NMGENCRC EQU 0029H 
NMGENROMVERS ION EQU O002AH 
NMGENALARMHOOK EQU 002BH 
NMGENALARMUNHOOK EQU 002CH 
NMGENALARMID EQU 002DH 
NMGENPASSWORDSET EQU 002EH 
NMGENPASSWORDTEST EQU O002FH 
NMGENPASSWORDCONTROL EQU 0030H 
NMGENPASSWORDQUERY EQU 0031H 
NMGENTICKLE EQU 0032H 
NMGENSETCONFIG EQU 0033H 
NMGENMASKINIT EQU 0034H 
NMGENMASKENCRYPT EQU 0035H 
NMGENMASKDECRYPT EQU 0036H 
NMGENSETONEVENTS EQU 0037H 
NMGENGETAUTOMAINS EQU 0038H 
NMGENSETAUTOMAINS EQU 0039H 
FLOATMANAGER EQU 008CH 
NMFLOATSIN EQU OO00H 
NMF LOATCOS EQU 0001H 
NMF LOATTAN EQU 0002H 
NMF LOATASIN EQU 0003H 
NMF LOATACOS EQU 0004H 
NMF LOATATAN EQU 0005H 
NMF LOATEXP EQU OO06H 
NMF LOATLN EQU 0O007H 
NMF LOATLOG EQU 0008H 
NMF LOATSQRT EQU 0009H 
NMF LOATPOW EQU OOOAH 
NMF LOATRAND EQU OOOBH 
NMF LOATMOD EQU OOOCH 
NMF LOATINT EQU OOODH 


EPOC O/S SYSTEM SERVICES 


WSERVOPCODES 


HWMANAGER 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


NMH 


WCOMBOON 


WCOMBOOFF 


WPACKSON 


WPACKSOFF 


WSETA2CONTROLIBITS 


WCLEARA2CONTROLIBITS 


WREADA2CONTROL1 


WWRITEA2CONTROLI 


WSETA2CONTROL2BITS 


WCLEARA2CONTROL2BITS 


WREADA2CONTROL2 


WWRITEA2CONTROL2 


WSETA2CONTROL3BITS 


WCLEARA2CONTROL3BITS 


WREADA2CONTROL3 


WWRITEA2CONTROL3 


WSELECTCHANNEL 


WGETSUPPLYSTATUS 


WLCDCONTRASTDELTA 


WREADLCDCONTRAST 


WSWITCHOFF 


WNULLFRAME 


WEXIT 


WGETCOMBO 


WFREECOMBO 


WGETCHANNEL 


WFREECHANNEL 


WGETPSUTYPE 


WSUPPLYWARNINGS 


WFORCESUPPLYREADING 


WGETBACKLIGHT 


WSETBACKLIGHT 


WBACKLIGHT 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


008D 


OO8E 


001D 


OO1E 


OO1F 


NMHWCOMBOONINPUT 


NMHWSUPPLYINFO 


NMHWGETSCANCODES 


GENDATASEGMENT 


PROCPANIC 


PROCCOPYFROMBYID 


PROCCOPYTOBYID 


CHARISDIGIT 


CHARISHEXDIGIT 


CHARISPRINTABLE 


CHARISALPHABETIC 


CHARISALPHANUMERIC 


CHARISUPPERCASE 


CHARISLOWERCASE 


CHARISSPACE 


CHARISPUNCTUATION 


CHARISGRAPHIC 


CHARISCONTROL 


CHARTOUPPERCHAR 


CHARTOLOWERCHAR 


CHARTOFOLDEDCHAR 


BUFFERCOPY 


BUFFERSWAP 


BUFFERCOMPARE 


BUFFERCOMPAREFOLDED 


BUFFERMATCH 


BUFFERMATCHFOLDED 


BUFFERLOCATE 


BUFFERLOCATEFOLDED 


BUFFERSUBBUFFER 


w 


UFFERSUBBUFFERFOLDED 


w 


UFFERJUSTIFY 


STRINGCOPY 


STRINGCOPYFOLDED 


STRINGCONVERTTOFOLDED 


STRINGCOMPARE 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


0021H 


0022H 


EPOC O/S SYSTEM SERVICES 


STRINGCOMPAREFOLDED 


STRINGMATCH 


STRINGMATCHFOLDED 


STRINGLOCATE 


STRINGLOCATEFOLDED 


STRINGLOCATEINREVERSE 


STRINGLOCATEINREVERSEFOLDED 


STRINGSUBSTRING 


STRINGSUBSTRINGFOLDED 


STRINGLENGTH 


STRINGVALIDATENAME 


LONGINTCOMPARE 


LONGINTMULTIPLY 


LONGINTDIVIDE 


LONGUNS IGNEDINTCOMPARE 


LONGUNSIGNEDINTMULTIPLY 


LONGUNSIGNEDINTDIVIDE 


F LOATADD 


7] 


LOATSUBTRACT 


7] 


LOATMULTIPLY 


7] 


LOATDIVIDE 


7] 


LOATCOMPARE 


7] 


LOATNEGATE 


7] 


LOATTOINT 


7] 


LOATTOUNSIGNEDINT 


7] 


LOATTOLONG 


7] 


LOATTOUNS IGNEDLONG 


NTTOFLOAT 


UNS IGNEDINTTOFLOAT 


LONGTOF LOAT 


UNS IGNEDLONGTOFLOAT 


LIBSEND 


LIBSENDSUPER 


LIBSENDEXACT 


LIBENTER 


LIBLEAVE 


DUMMY 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


fo} 

fo} 

Q 

ws 
I 


fo} 

oO 

a 

ol 
r 


oO 

oO 

a 

~ 
r 


fo) 
(>) 
Q 
aa 
I 


fo} 

fo} 

Q 

iw) 
i 


OOCFH 


GENINTBYNUMBER 


WSERVFUNCTIONS 


LIBSENDEXIT 


DBFMANAGER 


NMDBFOPEN 


NMDBFCLOSE 


NMDBFF LUSH 


NMDBF TRASH 


NMDBFCOP YDOWN 


NMDBFCOMPRESS 


NMDBFCOPYFILE 


NMDBFFILESIZE 


NMDBFEXTHEADERREAD 


NMDBFEXTHEADERWRITE 


NMDBFVERSION 


NMDBFABSREADSENSE 


NMDBFABSREAD 


NMDBFNEXTREAD 


NMDBFBACKREAD 


NMDBFFIRSTREAD 


NMDBFLASTREAD 


NMDBFAPPEND 


NMDBFERASEREAD 


NMDBFUPDATE 


NMDBFF INDREAD 


NMDBF SENSE 


NMDBF COUNT 


NMDBFDESCRECORDREAD 


NMDBFDESCRECORDWRITE 


NMDBFF INDREADFIELD 


LIBENTERSEND 


IOKEYANDMOUSESTATUS 


STRINGCAPITALISE 


PROCINDSTRINGCOPYFROMBYID 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


A INTERRUPT AND FUNCTION NUMBERS 


0OD5 


0O0D6 


OOD7 


00D8 


EPOC O/S SYSTEM SERVICES 


IONEXTHALFSECONDSTATUS 


IOSERMANAGER 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


NM 


OSEROPEN 


OSERADDHANDLER 


OSERREMOVEHANDLER 


OSERSETHANDLER 


OSERHANDLERSAVEERROR 


OSEROPENHANDLER 


OSEROPENT IMERHANDLER 


OSERFREE 


OSERCLOSETIMERHANDLER 


OSERDETACHFREE 


OSERTIMEROPEN 


OSERTIMERCANCEL 


OSERTIMERCLOSE 


OSERATTACHONOPENCHAN 


OSERSENSEONOPENCHAN 


OSERONOPENCHAN 


OSERCHECKWRITESI 


OSERCHECKREADSTI 


OSERS IGNALUSERWRITEOK 


OSERSIGNALUSERWRITE 


OSERS IGNALUSERREADOK 


OSERS IGNALUSERREAD 


OSERS IGNALUSER 


OSERQUEUEREAD 


OSERQUEUEWRITE 


OSERQUEUESUPER 


OSERQUEUETIMER 


OSERCANCELIOREQUEST 


OSERCANCELALLSIGNALUSER 


OSERS IGNALCOMP LETEOK 


OSERSIGNALCOMPLETE 


OSERSYNCWRITE 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


EQ 


OODD 


OODE 


Additional Interrupt and Function numbers 


A INTERRUPT AND FUNCTION NUMBERS 


The majority of the additional EPOC system services functions described in this section were introduced 


for the Series 3c and Siena. 


With the exception of the HC, all the services are, in principle, available on any machine that contains 
EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in 


this section should generate an =E_GEN_NsuP error. 


Some services require the presence of hardware that is not built into all machines in the SIBO range. If 
the relevant hardware is not present on a particular machine, calling the service will either have no effect 


or return an error of E_GEN_NSUP. 


Alphabetical list of extra functions 


HWMANAGER 


NMHWENABLEAUTOBATRESET 
NMHWEXPANSIONOFF 
NMHWEXPANSIONON 
NMHWGETBATDATA 
NMHWRELOGPACKS 
NMHWRESETBATTERYSTATUS 
NMHWRETURNEXPANS IONPORTSTATE 
NMHWRETURNTICKCOUNT 
NMHWSETIRPOWERLEVEL 


IOMANAGER 


NMIOPLAYSOUNDAO 


Numerical list of extra functions 


IOMANAGER 


NMIOPLAYSOUNDAO 


HWMANAGER 


NMHWRESETBATTERYSTATUS 
NMHWENABLEAUTOBATRESET 
NMHWGETBATDATA 
NMHWRELOGPACKS 
NMHWSETIRPOWERLEVEL 
NMHWRETURNTICKCOUNT 
NMHWRETURNEXPANSIONPORTSTATE 
NMHWEXPANSIONON 
NMHWEXPANSIONOFF 


EQ 


EQ 
EQ 
EQ 
EQ 
EQ 
EQ 
EQ 
EQ 
EQ 


EQ 


EQ 


EQ 


EQ 


aq 


GaGQaGQGGaGaaGAaaGG 


GaGa aqqaqaaaqaaG 


OO8EH 


002bH 
0033H 
0032H 
002cH 
002eH 
002aH 
0031H 
0030H 
O02fH 


0086H 


0024H 


0086H 


0024H 


008EH 


002aH 
002bH 
002cH 
002eH 
OO2fH 
0030H 
0031H 
0032H 


0033H 


APPENDIX B 


ENVIRONMENT VARIABLES 


This document is a beta version and is subject to change. 


This chapter documents all environment variables that, at the time of writing, are created or read by 
Psion’s software running on SIBO machines. Note that the names of all such environment variables 
contain the ‘$’ character. 


Environment variables survive a soft reset but are cleared on a hard reset. Some environment variables 
will be restored to their default values, by being loaded from a ROM initialisation file, on a hard reset. 
The set of environment variables that are restored in this way depends on both the machine type and the 
machine’s localisation (language). 


PLIB 


EM$ 


This environment variable is used by the CLIB and PLIB startup modules. It contains a string that 
specifies a search path for the 8087 emulator, sys$8087. Idd. 


Window server 
$WS_FL 


On an HC with version 3.5 of the window server, and in all machines that use version 4 or later, the 
initial value of the internal parameter that is set by wsystem is loaded from the sws_FL environment 
variable when the window server starts. 


After setting sws_r1 to the desired worp value, you must reset the HC by pressing the recessed reset button 
to make the new value effective. 


The wsystem flags parameter is made up by oring a number of bit fields of the form wsERV_FLAG_Xxx. 


After a hard reset on an HC with version 3.5 of the window server, the sws_FL environment variable does 
not exist (which is equivalent to it being zero). 


The following example program sets the sws_FL environment variable: 


#include <plib.h> 
#include <wlib.h> 


GLDEF_C INT main(VOID) 
{ 
WORD flags; 


flags=WSERV_FLAG_NO_NOTIFIER_REBOOT |WSERV_FLAG_HOOK_NOTIFIER 
| WSERV, FLAG LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW; 

return (p_setenviron("SWS_FL",6,&flags,2))j; 

} 


EPOC O/S SYSTEM SERVICES 


After running this program and resetting the HC, the window server will: 
e provide the notifier service 
e report low battery voltages 
e present a hung-up status window if an application hangs 


e report a process that terminates with a panic or with a negative reason number 


$WS_FNTS 


This environment variable contains a series of words, each of which contains the index of a font used by 
the window server. The fonts are as follows: 


e System font 

e §=6Notifier/Alert font 

e §=©Status Window font 

e Symbols font used for the status window diamond symbol 
e Medium 2 digital clock font 

e Medium 2 date font 

e =©Notifier/alert button font 


e Small status window clock font 


$WS_IF 


On the HC, the font used for output that is not graphics context directed is determined by the sws_1F 
("Internal Font") environment variable. 


This should contain a worp binary value of 0 for ws_ront_Base, | for ws_FoNT_BASE+1, and so on. If you 
change the value of sws_1Fr, you must reset the machine by pressing the recessed reset button to effect the 
change. 


The "factory" setting of sws_1F is 4 (which selects the S3 font). 


$WS_SD 


Pressing SHIFT-CTRL-PSION-S on an MC, S3, S3a, S3c, Siena or a Workabout saves the current screen to a 
file called screen.pic in the current path of the window server. Any existing file of the same name is 
replaced. 


In practice, the current path of the window server on a SIBO machine is always LOC::M:\ (it is defined 
when the window server process is started - well before you have any chance of influencing it). 


However, if an environment variable with the name $WS_SD exists, the window server uses its value to 
open the file to be created. For example, running the following program: 


#include <p_std.h> 


GLDEF_C INT main(VOID) 
{ 
p_setenv ("SWS_SD", "B:\\SCREEN.PIC"); 
return (0); 


} 


subsequently causes the screen dump to be written to the root directory of the local B: drive. 


If the save fails for any reason (such as disk full), the file is not produced and no notification of the failure 
is given. 


You can use this behaviour to disable the SHIFT-CTRL-PSION-S screen dump key by setting up sws_sp to 
contain an illegal file specification. For example, just inserting the following line of code: 


p_setenv("SWS_SD",""); 


disables the screen dump key. 


B ENVIRONMENT VARIABLES 


$WS_SF, $WS_SF2 and $WS_SF4 


On the HC, the Siena and the Series 3, Series 3a and Series 3c, the system font is determined by the 
$wWS_SF environment variable which should contain a worp binary value of 0 for ws_rFoNT_BASE, a WORD 
binary value of | for ws_rontT_BasE+1, and so on. If you change the value of sws_sF, you must reset the 
machine by pressing the recessed reset button to effect the change. 


On the MC, the system font is determined in the same way, except that two alternative environment 
variables are used; sws_sr2 and sws_sr4. If the screen has fewer than 300 lines (as on the MC200), 
$ws_sF2 is used. Otherwise (as on the MC400), sws_sra is used. 


The following program illustrates how the environment variable may be changed. 
#include <p_std.h> 
GLDEF_C INT main(VOID) 
{ 


WORD flags; 


flags=1; /* choose WS_FONT_BASE+1 */ 
return (p_setenviron("SWS_SF",6,&flags,2)); 
} 


Changing the system font may have an adverse effect on existing applications. 


HWIM 


M$V 


Evaluator format preferences, stored as an HWIM extTENDED_MEM_VALUES Structure. This environment 
variable is read and written by the ws_eval_env method of the wssrv class. The default values are: 


evalDegrees DEGREES_MODE 
calcDegrees DEGREES_MODE 
memVal.evalFormat P_DTOB_FIXED 
memVal.evalDPlaces EVAL_DEFAULT_PLACES 
memVal.calcFormat P_DTOB_GENERAL 
memVal.calcDPlaces CALC_DEFAULT_PLACES 
memVal.values[0] to 0.0 
memVal.values[9] 


D$X 


Telephone dialling preferences, stored as a DIAL_ENvaR structure. The environment variable is read and 
written by ws_dial_env method of the wszrv class. The normal default values are: 


toneLengthTicks 8 
delayLengthTicks 8 
pauseLengthTicks 48 
dialoutCode[] “9,” 


These values may vary in non-English machines. 
L$X 


This environment variable is read by the Series 3c only, to provide a possible extra option for the ‘Use’ 
choice list of the System Screen’s ‘Communications’ dialog. 


EPOC O/S SYSTEM SERVICES 


If it exists, the environment variable should contain three leading byte counted items which are, in order: 
e text for the extra option, which will be appended to the choice list 
e the full file specification of the file to p_execc if the new option is selected 
e any additional command line data 


For example, to add an ‘IRcom’ option that, on selection, executes the file loc::m:\sys$irc.img, passing it 
the command line “-P1”, the environment variable could be set (using an HC-style Command 
Processor).by: 


set LS$X=\05IRCom\13L0C: :M:\SYSS$IRC.IMG\03-P1 


Additional command line options can be appended to any specified in the environment variable by use of 
the ‘Extra parameters’ line in the System screen’s ‘Communications’ dialog. 


ees] 
Printing 
P$D 


The type of the port used for printing, held as a zero terminated character containing a single ASCTI digit. 
The possible port types and their representations are: 


PRINTER_PORT_PARALLEL ‘0’ 
PRINTER_PORT_SERIAL ‘Tl 
PRINTER_PORT_FILE 2’ 
PRINTER_PORT_FAX ‘3’ 


The default value represents PRINTER_PORT_PARALLEL. 


These environment variables are set/created by the pRINTER pr_set_port_type method, and got by the 
PRINTER pr_port_data method, (see the FORM Reference manual). 


P$F 


The name of the print file, that is, the file to which printing is to be directed, held as a zero terminated 
character string. The default print file name is p.lis. 


This environment variable is set/created by the PRINTER pr_store_file method, and got by the pRINTER 
pr_port_data method, (see the FORM Reference manual). 


P$S 


The characteristics of the serial port when it is used for printing, held as a p_srcuar structure. The default 
values are: 


tbaud P_BAUD_9600 

rbaud P_BAUD_9600 

frame P_DATA_8 

parity 0) 

hand P_OBEY_XOFF | P_OBEY_DSR|P_IGN_CTS 
xoff 0x13 

xon Ox1l1 

flags 0 

tmask 0 


This environment variable is set/created by the PRINTER pr_store_srchar method, and got by the PRINTER 
pr_port_data method, (see the FORM Reference manual). 


B ENVIRONMENT VARIABLES 


P$M 


The specification of the current printer model, held as a zero terminated character string. The string 
contains an ASCII digit, followed by the name of a printer driver (.wdr) file, where the digit specifies the 
index number, starting from zero, of the particular model within the printer driver file. The default value 
is “OBJ.WDR’” (the file bj.wdr is present in the ROM of all relevant machines and contains only one 
model -that for the BJ-10e printer). 


This environment variable is set/created by the PRINTER pr_set_mode1 method, and got by the pRINTER 
pr_sense_model method, (see the FORM Reference manual). 


P$P 


This environment variable contains two bytes of data that specify the display preferences for print 
preview. The first byte is an ASCII digit specifying the number of pages to display. This must be in the 
range ‘1’ to ‘4’ inclusive. The second byte is also an ASCII digit, which may be ‘1’, indicating that 
margins are to be visible during print preview, or ‘0’. 


This environment variable is set/created by the prvvIEw wn_init method (see the XADD Reference 
manual). 


P$PP 


The port used for parallel printing, specified as a single ASCII character, for example, ‘B’. This 
environment variable should only be set on machines that have more than one port, such as the 
Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the printer class, in 
the FORM library. 


P$SP 


The port used for serial printing, specified as a single ASCII character, for example, ‘A’. This 
environment variable should only be set on machines that have more than one port, such as the 
Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the pRintER class, in 
the FORM library. 


P$Z 
The paper size, stored as a single ASCII digit. It is normally ‘0’ (A4) or ‘4’ (Letter). 


This environment variable is only used on the Siena and the Series 3c. It is not supported on Siena 
machines with a version number of 4.20 and below. 


PSIP 


A single ASCII character, specifying the port letter for the IR printing device. This environment variable 
is used on the Siena and the Series 3c only. 


P$PX 


This environment variable contains the device type and the serial characteristics for ‘Parallel’ printing. It 
is used only on the Siena and the Series 3c, which communicate with the Parallel cable via a serial 
interface. 


The environment variable contains a one byte device type (0 is parallel) followed by a p_srcuar struct, as 
defined in p_serial.h. 


EPOC O/S SYSTEM SERVICES 


Calculator application 
C$CALC 


This environment variable is used on the Siena and Series 3c machines only, to store Calculator display 
preferences. It contains the following structure: 


typedef struct 


INT bitmapId; 


INT currentView; /* store current Calc View */ 

INT statusWinSize; /* store status window size */ 

INT nDec; /* -l=off, or 0..4 fixed dec places */ 
INT Zoom; /* zoom setting for Advanced view */ 


DOUBLE memory; 
}CR_CALC_ENV_INFO; 


whose members have the following meanings: 
BitmapId for internal use only 
CurrentView 0=Desk view, 1=Advanced view 


StatusWinSize one of the Window server flags: w_sTATUS_WINDOW_OFF, W_STATUS_WINDOW_SMALL, 
or (Series 3c only) w_sTATUS_WINDOW_BIG 


NDec used by the Desk view: values can be 0 to 4 inclusive, to specify the fixed number of 
decimal places to display, or -1 to display a variable number of decimal places 


Zoom used by the Advanced view to contain the ID of the font used in the current zoom 
state. For the Siena, the allowed range of values is FonT_ID_swiss_s8 to 
FONT_ID_SWISS_8+3 inclusive, and for the Series 3c the range is FONT_ID_SWISS_8 
to FONT_ID_SwWIss_8+4 inclusive 


Memory the current contents of the Desk view’s memory. 


M$0MO0 to M$9M9 


These environment variables contain the current values of the ten (Advanced view) calculator memories. 


Note that the names of these environment variables are dependent on the names of the memories, as seen 
from within the Calculator application. If, for example, memory M2 is renamed to “Memory2”, the 
environment variable ms2m2 will be replaced by an environment variable with the name ms2mEmory2. 


The name of each of these environment variables will never exceed eleven characters. 


Tips application 

TW$S 

Contains permanent data for the Tips application. The data consists of a single byte containing two flags: 
0x02 if set, the display of tips is enabled 


0x04 if set, tips are displayed once per day, otherwise they are displayed whenever the 
machine is turned on 


B ENVIRONMENT VARIABLES 


World application 

Wsc 

Contains the display preferences for the World application, as three worps: 
clock type either wS_CLOCK_FORCE_ANALOG Of WS_CLOCK_FORCE_DIGITAL 
map colour either TRUE for a grey map or Fa.se for a black map 


distance units — one of wR_uNITS_MILES (0), WR_LUNITS_KILOMETERS (1) or WR_UNITS_NAUTICAL (2) 


WS$R 


This environment variable stores permanent data for the World database services. The content has three 
elements: 


e asignature for the world database file, including the file version, 
e data specifying the home city, 


e data specifying the default country, that is, the country to which telephone numbers are assumed 
to belong if a particular country is not specified. 


Spell/Thesaurus 
SP$DRV 


This environment variable identifies the drive that contains the Spellchecker’s global dictionary, as set 
from the Spell application’s Install menu option. It contains a single ASCII character that may be ‘A’, ‘B’ 
or ‘M’. 


SP$OPT 


This environment variable stores the preferences settings from the Spell application as a series of flags, 
stored in a single uworp. The contents affect the spellchecker and thesaurus (although not necessarily used 
by both) 


The content is an ored combination of the following set of values, selected by the user from the Spell 
application’s Preferences menu option: 


0x0100 if set, ignore words all in upper case 
0x0200 if set, ignore words containing punctuation 
0x0400 if set, ignore repeated words 

0x0800 if set, ignore the case of repeated words 
0x1000 if set, show the definitions window 
WP$SPEL 


This is used by all applications that may wish to access the Spellchecker. The content is a single byte with 
a value of zero, but has no significance; the mere existence of the environment variable indicates that the 
Spellchecker is currently installed. 


WP$THES 


This is used by all applications that may wish to access the Thesaurus. The content is a single byte with a 
value of zero, but has no significance; the mere existence of the environment variable indicates that the 
Thesaurus is currently installed. 


EPOC O/S SYSTEM SERVICES 


———— ee re] 
3Fax application 


FSX 


This environment variable contains two bytes of preferences. 


The first byte contains one of the ASCII characters ‘M’, ‘A’ or ‘B’, representing the drive that is currently 
used to store the application’s intermediate files. 


The second byte contains a combination of the following flags: 


0x01 if set, a new fax job is created on selection of ‘Print to fax’. Otherwise, the 
document is simply processed to produce an intermediate file, for later 
sending 

0x02 if set, intermediate files are automatically deleted after they have been sent 

F$XM 

Contains the current 3Fax modem parameters. 

F$XP 


Stores power usage data for the 3Fax device. Contains the time on batteries and the time on mains. 


Se ee ee eT) 
Email applications 


MAIL$ST 


This environment variable is used, with some differences in content, by both the Corporate and the 
Internet PsiMail applications. It is created by an email application whenever a mail session completes, to 
contain data passed from the message transfer agent (MTA) to the mail client. It is not a permanent store 
of data, as it is deleted and recreated every time the MTA starts. 


A MAILSST environment variable created by the Corporate mail application will not disrupt the Internet 
mail application, should it be run on the same machine, and vice versa. 


The content for the Corporate application consists of a sequence of five uworns, in the following order: 
e acount of the messages that were sent 
e acount of the messages that were received 
e acount of the messages that were not sent 
e acount of the messages that are marked as read 
e¢ a flag which, if set to TRUE, indicates that some messages were not received 
The content for the Internet application consists of a sequence of eight uworps, in the following order: 
e acount of the messages that were sent 
e acount of the messages that were received 
e acount of the messages that were not sent 
e acount of the messages that are marked as read 
e acount of messages that were deleted from the mail server 
e the return code from the MTA 
e the return code from the sending process (normally 0) 
e the return code from the receiving process (normally 0) 


As can be seen from the above lists, the first four items are common to both variants of MarLsst. 


B ENVIRONMENT VARIABLES 


Workabout 


The following environment variables are used only on Workabout machines. See also pspp and pssp, 
described in the Printing section of this chapter. 


S$SVER 


Contains a text string representing the Workabout Startup Shell version number, for example, “1.00F”. 


C$P@ 


This environment variable is set when exiting from the Workabout command processor. It contains a 
single ASCII character representing the current drive, with a default value of ‘M’. 


C$PA to C$PZ 


The environment variable cspa may be set when exiting from the Workabout command processor, to 
contain a text string representing the current path on drive A. It is not set if the drive A path is to the root 
directory. 


Similar environment variables may be set for all other possible drives - cspg to cspz inclusive. 
C$P£ 


This environment variable contains the parameters used by Link when accessed from the Workabout 
System Screen and/or Command Processor. 


C$P$ 


This environment variable is set following selection of the keyboard from the Command Processor or the 
System Screen. It contains a single byte whose binary value is either 0 (Standard keyboard selected) or | 
(Special keyboard selected). 


INDEX 


$WS_FL 

environment variable, B-1 
$WS_FNTS 

environment variable, B-2 
$WS_IF 

environment variable, B-2 
$WS_SD 

environment variable, B-2 
$WS_SF 

environment variable, B-3 
$WS_SF2 

environment variable, B-3 
$WS_SF4 

environment variable, B-3 
.wve files 

sound file format, 8-1 
active 

marking a process, 19-7 

unmarking a process, 19-8 
add 

two floats, 14-2 
adjust 

a heap memory cell size, 3-2 

size of a memory segment, 2-6 
alarm 

getting the server pid, 19-15 

hooking the interface, 19-15 

unhooking the interface, 19-15 
allocate 

a heap memory cell, 3-1 

re-allocating a heap memory cell, 3-2 
am 

getting the amtext, 19-11 
append 

a DBFrecord, 20-10 
arcsine 

float function, 15-1 
arctangent 

float function, 15-1 
asynchronous 

I/O, 8-2 

1/O without error reporting, 8-2 

message reception, 5-2 
attach 

a file system, 9-6 
auto-switch-off 

disable/enable if mains present, 19-16 

get state if mains present, 19-16 

processes and, 19-8 

processes and, 19-7 

resetting, 19-15 

setting value, 19-9 


Auto-switch-off 

Getting value, 19-9 
battery 

enable/disable reset, 21-10 

getting type, 19-11 

reset the status, 21-10 

return pointer to information, 21-11 

setting type, 19-11 
buffer 

comparing, 17-1 

comparing folded, 17-2 

copying, 17-1 

justifying, 17-4 

locating, 17-2 

locating folded, 17-2 

subbuffer, 17-3 

sub-buffer folded, 17-3 

swapping, 17-1 

wild card match, 17-3 

wild card match folded, 17-4 
BufferCompare 

compare buffers service, 17-1 
BufferCompareFolded 

compare buffers folded service, 17-2 
BufferCopy 

copy buffer service, 17-1 
BufferJustify 

justify a buffer service, 17-4 
BufferLocate 

locate a character in buffer service, 17-2 
BufferLocateFolded 


locate a character in buffer folded service, 


17-2 
BufferMatch 

match a wildcard buffer service, 17-3 
BufferMatchFolded 


match a wildcard buffer folded service, 17-4 


BufferSubBuffer 


find a sub-buffer in a buffer service, 17-3 


BufferSubBufferFolded 


find a sub-buffer in a buffer folded service, 


17-3 
BufferSwap 

swap buffers service, 17-1 
C$CALC 

environment variable, B-6 
C$P$ 

environment variable, B-9 
C$P@ 

environment variable, B-9 
C$PEL 

environment variable, B-9 
C$PA to C$PZ 

environment variables, B-9 
cancel 

message receive, 5-3 

playing back sound file, 8-13 

recording sound to file, 8-14 

signal from the supervisor, 5-5 

signal from the supervisor by type, 5-6 

signal from the supervisor I/O, 8-11 
capitalising 

a string, 18-1 


EPOC O/S SYSTEM SERVICES 


category 

copying data from, 6-7 
change 

size of a memory segment, 2-6 
character 

is a digit, 16-1 

is a hexadecimal digit, 16-1 

is alphabetic, 16-1 

is alphabetic or digit, 16-2 

is graphic, 16-3 

is lowercase, 16-2 

is printable, 16-1 

is punctuation, 16-2 

is space, 16-2 

is uppercase, 16-2 

to fold, 16-3 

to uppercase, 16-3 
Character 

is control, 16-3 

to lowercase, 16-3 
CharIsAlpha 

character is alphabetic service, 16-1 
CharIsAlphaNumeric 

character is alphabetic or digit service, 16-2 
CharIsControl 

character is control service, 16-3 


CharIsDigit 

character is a digit service, 16-1 
CharIsGraphic 

character is graphic service, 16-3 
CharIsHexDigit 


character is a hexadecimal digit service, 

16-1 
CharIsLowerCase 

character is lowercase service, 16-2 
CharIsPrintable 

character is printable service, 16-1 
CharIsPunctuation 

character is punctuation service, 16-2 
CharIsSpace 

character is space service, 16-2 
CharIsUpperCase 

character is uppercase service, 16-2 
CharToFoldedChar 

character to fold service, 16-3 
CharToLowerChar 

character to lower service, 16-3 
CharToUpperChar 

character to upper service, 16-3 
close 

a database file, 20-4 

afile, 8-8 

a locked or device segment, 2-5 

a memory segment, 2-4 

an I/Odevice, 8-8 
coldstart 

getting the reason for, 19-2 
command line 

getting, 19-6 
compare 

two buffers, 17-1 

two buffers case independent, 17-2 

two floats, 14-1 

two long integers, 13-1 


two strings, 18-1 

two strings case independent, 18-2 

two unsigned long integers, 13-2 
compress 

a database file, 20-5 
connect 

to the file server, 9-1 
ConvArgumentsToBuffer 

convert arguments to buffer service, 12-2 
conversion 

arguments to buffer, 12-2 

floating point number to buffer, 12-4 

integer to buffer, 12-1 

long integer to buffer, 12-2 

string to floating point number, 12-5 

string to integer, 12-3 

string to long integer, 12-3 

string to unsigned integer, 12-2 

string to unsigned long integer, 12-2 

unsigned integer to buffer, 12-1 

unsigned long integer to buffer, 12-1 
convert 

a string to folded, 18-1 

float to signed integer, 14-3 

float to signed long, 14-2 

float to unsigned integer, 14-3 

float to unsigned long, 14-2 

signed integer to float, 14-3 

signed long to float, 14-3 

unsigned integer to float, 14-3 
ConvFloatToBuffer 

convert floating point number to buffer 

service, 12-4 
ConvintToBuffer 

convert integer to buffer service, 12-1 
ConvLongIntToBuffer 

convert long integer to buffer service, 12-2 
ConvStringToFloat 

convert string to floating point number, 

12-5 
ConvStringToInt 

convert string to integer, 12-3 
ConvStringToLongInt 

convert string to long integer, 12-3 
ConvStringToUnsignedInt 

convert string to unsigned integer, 12-2 
ConvStringToUnsignedLongInt 

convert string to unsigned long integer, 

12-2 
ConvUnsignedIntToBuffer 

convert unsigned integer to buffer service, 

12-1 
ConvUnsignedLongIntToBuffer 

convert unsigned long integer to buffer 

service, 12-1 
copy 

a buffer, 17-1 

a database file, 20-5 

a string, 18-1 

a string folded, 18-1 

copying down a DBF record, 20-5 

data from a process, 10-8 

data to a process, 10-9 

from a category, 6-7 


from a memory segment, 2-7 
strings from a process, 10-9 
to a memory segment, 2-6 
cosine 
float function, 15-1 
count 
the number of DBF records, 20-13 
country data 
getting, 19-2 
setting, 19-2 
CRC 
generating, 19-12 
create 
a memory segment, 2-3 
an object by handle, 6-3 
an object by number, 6-3 
a process, 10-4 
a semaphore, 4-1 
a task, 10-4 
D$xX 
environment variable, B-3 
data segment 
of the operating system, 19-2 
Database file 
appending a record, 20-10 
closing, 20-4 
compressing, 20-5 
copying, 20-5 
copying down a record, 20-5 
counting the number of records, 20-13 
Deleted records, 20-5 
end of file, 20-2 
erasing a record, 20-11 
file buffering, 20-2 
file structure, 20-1 
finding a record, 20-12 
finding a record by field, 20-13 
flushing, 20-4 
getting the size, 20-6 
Getting the version number, 20-8 
index table, 20-2 
number of records, 20-3 
opening, 20-3 
reading an absolute record, 20-8 
reading and sensing an absolute record, 
20-9 
reading the descriptive record, 20-7 
reading the extended header, 20-7 
reading the first record, 20-10 
reading the last record, 20-10 
reading the next record, 20-9 
reading the previous record, 20-9 
sensing the record number, 20-13 
trashing the buffer, 20-4 
updating a record, 20-11 
writing the descriptive record, 20-8 
Writing the extended header, 20-7 
date 
abbreviated name of day, 11-5 
abbreviated name of month, 11-5 
convert date to day seconds, 11-3 
convert day seconds to date, 11-3 
convert day seconds to system time, 11-3 


INDEX 


convert the system time to day seconds, 
11-3 
getting am and pm text, 19-11 
getting suffixes, 19-11 
getting the systemdate, 11-2 
name of day, 11-4 
name of month, 11-4 
number of days in a month, 11-4 
set file, 9-8 
setting the system date, 11-2 
weekday number, 11-4 
day 
abbreviated name of, 11-5 
name of, 11-4 
days 
number of, 11-4 
DbfAbsRead 
reading an absolute DBF record service, 
20-8 
DbfAbsReadSense 
reading and sensing an absolute DBF record 
service, 20-9 
DbfAppend 
append a DBF record service, 20-10 
DbfBackRead 
read the previous DBF record service, 20-9 
DbfClose 
closing a database file service, 20-4 
DbfCompress 
compressing a database file service, 20-5 
DbfCopyDown 
copying down a DBF record service, 20-5 
DbfCopyFile 
copying a database file service, 20-5 
DbfCount 
count the number of DBF records service, 
20-13 
DbfDescRecordRead 
reading a DBF descriptive record service, 
20-7 
DbfDescRecord Write 
writing a DBF descriptive record service, 
20-8 
DbfEraseRead 
erasing a DBF record service, 20-11 
DbfExtHeaderRead 
reading a DBF extended header service, 
20-7 
DbfExtHeaderWrite 
writing a DBF extended header service, 
20-7 
DbfFileSize 
getting the size of a database file service, 
20-6 
DbfFindRead 
finding a DBF record service, 20-12 
DbfFindReadField 
finding a DBF recordbyfield service, 20-13 
DbfFirstRead 
read the first DBF record service, 20-10 
DbfFlush 
flushing a database file service, 20-4 
DbfLastRead 
read the last DBF record service, 20-10 


iii 


EPOC O/S SYSTEM SERVICES 


DbfNextRead 

read the next DBF record service, 20-9 
DbfOpen 

opening a database file service, 20-3 
DbfSense 

sense the current DBF record number 

service, 20-13 
DbfTrash 

trashing the DBF buffer service, 20-4 
DbfUpdate 

updating a DBF record service, 20-11 
DbfVersion 

getting the DBF version number service, 

20-8 
deferred mode 

setting, 19-4 
delete 

a device driver, 7-3 

a file or directory, 9-3 

a memory segment, 2-4 

a semaphore, 4-1 
destroy 

an object, 6-4 
detach 

a file system, 9-7 
DevDelete 

delete a device driver service, 7-3 
DevFind 

find all devices service, 7-4 
DevGetPDDAddress 

get PDD entry point service, 7-2 
DevHold 

hold all device drivers service, 7-2 
devices 

calling a vector, 7-5 

delete a device driver, 7-3 

drivers, 7-1 

find all devices, 7-4 

getting the PDD entry point, 7-2 

hold all device drivers, 7-2 

install a device driver, 7-2 

load a logical device driver, 7-3 

load a physical device driver, 7-3 

names, 7-1 

open a physical device driver, 7-1 

query the number of units, 7-4 

remove a device driver, 7-4 

resume all device drivers, 7-3 
devices and files 

and I/O, 8-1 
DevInstall 

install a device driver service, 7-2 
DevLoadLDD 

load a logical device driver service, 7-3 
DevLoadPDD 

load a physical device driver service, 7-3 
DevOpenPDD 

open PDD service, 7-1 
DevQueryUnits 

query the number of units service, 7-4 
DevRemove 

remove a device driver service, 7-4 
DevResume 

resume all device drivers service, 7-3 


DevVector 
call a device vector, 7-5 
directory 
changing, 9-7 
deleting, 9-3 
getting status, 9-4 
making, 9-6 
renaming, 9-4 
setting status, 9-4 
display type 
getting, 19-2 
divide 
floats, 14-1 
two long integers, 13-1 
two unsigned long integers, 13-2 
dummy 
call, 19-3 
service, 19-3 
DYL 
getting a handle, 6-3 
dynamic library 
finding, 6-2 
getting a handle, 6-3 
linking, 6-2 
loading, 6-1 
loading multiple, 6-6 
names, 6-1 
unloading, 6-2 
EM$ 
environment variable, B-1 
endoffile 
database file, 20-2 
enter 
a control region, 6-7 
leaving from a control region, 6-7 
environment variable 
$WS_FL, B-1 
$WS_FNTS, B-2 
$WS_IF, B-2 
$WS_SD, B-2 
$WS_SF, B-3 
$WS_SF2, B-3 
$WS_SF4, B-3 
C$CALC, B-6 
C$P$, B-9 
C$P@, B-9 
C$PE£, B-9 
C$PA to C$PZ, B-9 
contents and names of all, B-1 
D$X, B-3 
deleting buffer, 19-13 
deleting string, 19-14 
EM$, B-1 
F$X, B-8 
F$XM, B-8 
F$XP, B-8 
finding buffer, 19-13 
finding string, 19-14 
getting buffer, 19-12 
getting string, 19-14 
L$X, B-3 
M$0MO, B-6 
M$1M1, B-6 
M$2M2, B-6 


MAILSST, B-8 


names and contents of all, B-1 


P$D, B-4 
P$F, B-4 
P$IP, B-5 
P$M, B-5 


S$SVER, B-9 

setting buffer, 19-12 

setting string, 19-14 

SP$DRV, B-7 

SP$OPT, B-7 

TW$S, B-6 

WSC, B-7 

WSR, B-7 

WPS$SPEL, B-7 

WP$THES, B-7 
Environment variable 

Finding all, 19-13 
epocsibo.inc 

Include file, 21-10 
erase 

aDBFrecord, 20-11 
error 

notificationof, 19-5 
errors 

gettingthetext, 19-3 
execute 

animagefile, 9-1 
exits 

watchingall, 10-8 
expansion port 

sense state of, 21-12 
exponentiation 

floatfunction, 15-2 
F$X 

environment variable, B-8 
F$XM 

environment variable, B-8 
F$XP 

environment variable, B-8 
FilChangeDirectory 


change directory service, 9-7 


FilConnect 


file server connect service, 9-1 


FilDelete 


delete file or directory service, 9-3 


filebuffering 

database file, 20-2 
filemanagement 

attaching a file system, 9-6 


INDEX 


change directory, 9-7 

connect to the file server, 9-1 

deleting, 9-3 

detaching a file system, 9-7 

execute a program file, 9-1 

get current path, 9-2 

get current path by ID, 9-7 

getting device status, 9-5 

getting status, 9-4 

getting system status, 9-5 

local file system changed, 9-8 

making a new directory, 9-6 

parse a filename, 9-2 

read a local device directly, 9-9 

read media information of a local device, 

9-9 

renaming, 9-4 

set current path, 9-3 

set file date, 9-8 

set initial path, 9-8 

setting status, 9-4 

test path available, 9-3 
filename 

generic parse, 19-3 
fileserver 

process, 9-1 
filestructure 

database file, 20-1 
FilExecute 

execute image file service, 9-1 
FilLocChanged 

report if the local file system has changed, 

9-8 
FilLocDevice 

read media information of a local device, 

9-9 
FilLocReadPdd 

read a local device directly, 9-9 
FilMakeDirectory 

make a new directory service, 9-6 
FilOpenUnique 

I/O open a unique filename service, 9-6 
FilParse 

parse filename service, 9-2 
FilPathGet 

get current path service, 9-2 
FilPathGetByld 

get current path by ID service, 9-7 
FilPathSet 

set current path service, 9-3 
FilPathTest 

test path available service, 9-3 
FilRename 

rename a file or directory service, 9-4 
FilSetFileDate 

set file date service, 9-8 
FilSetInitialPath 

set initial path service, 9-8 
FilStatusDevice 

get device status service, 9-5 
FilStatusGet 

get file or directory status service, 9-4 
FilStatusSet 

setfile or directory status service, 9-4 


EPOC O/S SYSTEM SERVICES 


FilStatusSystem 
get file system status, 9-5 
FilSystemAttach 
attach a file system service, 9-6 
FilSystemDetach 
detach a file system service, 9-7 
find 
a DBF record, 20-12 
a DBF record by field, 20-13 
a dynamic library, 6-2 
all Devices, 7-4 
all processes, 10-7 
all segments, 2-6 
float 
adding, 14-2 
arc sine function, 15-1 
arc tangent function, 15-1 
comparing, 14-1 
conversion to a buffer, 12-4 
converting signed integer to float, 14-3 
converting signed long to float, 14-3 
converting to signed integer, 14-3 
converting to signed long, 14-2 
converting to unsigned integer, 14-3 
converting to unsigned long, 14-2 


converting unsigned integer to float, 14-3 


cosine function, 15-1 

dividing, 14-1 

exponentiation function, 15-2 
logarithm function, 15-2 
modulo function, 15-3 
multiplying, 14-1 

natural logarithm function, 15-2 
negating, 14-2 

power function, 15-3 

random number function, 15-3 
sine function, 15-3 

square root function, 15-4 
subtracting, 14-2 

tangent function, 15-4 

to integer, 15-2 


FloatAdd 

add floats service, 14-2 
FloatASin 

arc sine service, 15-1 
FloatATan 

arc tangent service, 15-1 
FloatCompare 

compare floats service, 14-1 
FloatCos 

cosine service, 15-1 
FloatDivide 

divide floats service, 14-1 
FloatExp 

exponentiation service, 15-2 
FloatInt 

integer service, 15-2 
FloatLn 

natural logarithm service, 15-2 
FloatLog 

logarithm service, 15-2 
FloatMod 


modulo service, 15-3 


FloatMultiply 

multiply floats service, 14-1 
FloatNegate 

negate floats service, 14-2 
FloatPow 

power service, 15-3 
FloatRand 

random number service, 15-3 
FloatSin 

sine service, 15-3 
FloatSqrt 

square root service, 15-4 
FloatSubtract 

subtract floats service, 14-2 
FloatTangent 

tangent service, 15-4 
FloatToInt 


convert float to signed integer service, 14-3 


FloatToLong 
convert float to long service, 14-2 
FloatToUnsignedInt 


convert float to unsigned integer service, 


14-3 
FloatToUnsignedLong 

convert float to long service, 14-2 
flush 

a database file, 20-4 
free 

a heap memory cell, 3-3 

a message, 5-4 
GenAlarmHook 

hook the alarm interface, 19-15 
GenAlarmld 

get the pid of the alarm server, 19-15 
GenCrc 

generate a CRC check, 19-12 


GenDataSegment 

operating system data segment, 19-2 
GenDeferredMode 

set deferred mode, 19-4 
GenEnvBufferDelete 

delete environment variable, 19-13 
GenEnvBufferFind 

find environment variable, 19-13 
GenEnvBufferGet 

get environment variable, 19-12 
GenEnvBufferSet 

set environment variable, 19-12 
GenEnvStringDelete 

delete environment variable, 19-14 
GenEnvStringFind 

find environment variable, 19-14 
GenEnvStringGet 

get environment variable, 19-14 
GenEnvStringSet 

set environment variable, 19-14 
GenGetAmPmText 

get the am and pm text, 19-11 
GenGetAutoMains 


get state for auto-switch-off if mains 

present, 19-16 
GenGetAutoSwitchOffValue 

get the auto switch off value, 19-9 


GenGetBatteryType 

get the battery type, 19-11 
GenGetCommandLine 

get the command line, 19-6 
GenGetCountryData 

get country dependent data, 19-2 
GenGetErrorText 

get error text, 19-3 
GenGetLanguageCode 

get the language code, 19-10 
GenGetNotifyState 

get notify state, 19-8 
GenGetOsData 

get O/S data, 19-3 
GenGetRamSizelInParas 

get address able system RAM size, 19-6 
GenGetSoundFlags 

get the sound flags, 19-7 
GenGetSuffixes 

get suffix text, 19-11 
GenGetText 

get operating system text, 19-8 
GenIntByNumber 

interrupt by number, 19-12 
GenLcdType 

LCD type, 19-2 
GenMarkActive 
mark process as active, 19-7 
GenMarkNonActive 
mark process as non-active, 19-8 
GenNotify 
notification service, 19-4 
GenNotifyError 
notification of error, 19-5 
GenNotifyHook 

hook the notifier interface, 19-5 
GenParse 

generic parse, 19-3 


GenResetRevector 

release an interrupt, 19-10 
GenRom Version 

get the ROM version, 19-1 
GenSetAutoMains 


disable/enableauto-switch-off if mains 

present, 19-16 
GenSetAutoSwitchOffValue 

set the auto switchoff time, 19-9 
GenSetBatteryType 

set the battery type, 19-11 
GenSetCountryData 

set country dependent data, 19-2 
GenSetNotifyState 

set notify state, 19-9 
GenSetOnEvents 

enable/disable on events, 19-16 
GenSetRevector 

capture an interrupt, 19-9 
GenSetSoundFlags 

set the sound flags, 19-7 
GenSound 

make a sound with the piezo, 19-7 
GenStartReason 

getting the system cold start reason, 19-2 


INDEX 


GenTickle 

reset the autoswitch off timer, 19-15 
GenUnAlarmHook 

unhook the alarm interface, 19-15 
GenUnNotifyHook 


unhook the notifier interface, 19-6 
GenVersion 
operating system version number, 19-1 
granularity 
of the heap memory, 3-3 
halfseconds 
query completion, 8-12 
signal on next half second, 8-11 
handle 
of a DYL, 6-3 
of a dynamic library, 6-3 
handler 
adding, 8-6 
adding an application, 8-9 
enabling, 8-6 
enabling an application, 8-10 
removing, 8-6 
removing an application, 8-10 
hardware 
capturing the combo subsystem, 21-5 
changing the LCD contrast, 21-6 
clearing bits in Asic2 register1, 21-2 
clearing bits in Asic2 register2, 21-3 
clearing bits in Asic2 register3, 21-3 
enable/disable reset, 21-10 
exiting toDOS, 21-5 
expansion port sense state of, 21-12 
freeing a channel, 21-6 
freeing the combo subsystem, 21-5 
get additional power supply data, 21-10 
getting achannel, 21-5 
getting backlight control, 21-7 
getting current LCD contrast, 21-7 
getting supplies status, 21-6 
getting supplies warnings, 21-6 
getting the power supply type, 21-6 
Honda connector power disable, 21-12 
Honda connector power enable, 21-12 
infrared power level set, 21-11 
operating the backlight, 21-7 
reading Asic2 register2, 21-3 
reading Asic2 register3, 21-4 
reset the battery status, 21-10 
return battery information, 21-11 
scan state of all keys, 21-8 
select serial channel, 21-4 
sending a serial null frame, 21-4 
setting backlight control, 21-7 
setting bits in Asic2 register1, 21-2 
setting bits in Asic2 register2, 21-2 
setting bits in Asic2 register3, 21-3 
SSDs relog, 21-11 
switching off, 21-4 
switching off the combo, 21-1 
switching off the SSDs, 21-1 
switching on the combo, 21-1 
switching on the combo in input mode, 
21-10 
switching on the SSDs, 21-1 


EPOC O/S SYSTEM SERVICES 


tick count sense current, 21-11 
writing Asic2 register 1, 21-2 
writing Asic2 register2, 21-3 
writing Asic2 register3, 21-4 


Hardware 

Reading Asic2 register1, 21-2 
HeapAdjustCellSize 

adjust heap cellsize service, 3-2 
HeapAllocateCell 

allocate heap cell service, 3-1 
HeapCellSize 

size of heap memory cell, 3-3 
HeapFreeCell 

free a heap cell service, 3-3 
HeapFreeMemory 


size of available heap memory, 3-3 
heap memory 

dynamics, 3-1 
HeapReAllocateCell 

re-allocate heap cell service, 3-2 
HeapSetGranularity 

set heap grow by parameter service, 3-3 
Honda connector 

power disable, 21-12 

power enable, 21-12 
HwBackLight 

operating the backlight, 21-7 
HwClearA2Control1 Bits 

clearing bits in Asic2 register 1, 21-2 
HwClearA2Control2Bits 

clearing bits in Asic2 register 2, 21-3 
HwClearA2Control3Bits 

clearing bits in Asic2 register 3, 21-3 
HwComboOff 

switch off the combo, 21-1 
HwComboOn 

switch on the combo, 21-1 
HwComboOnInput 


switch on the combo in input mode, 21-10 


HwEnableAutoBatReset 

enable/disable battery reset on recharge, 

21-10 
HwExit 

exit the program, 21-5 
HwExpansionOff 

Honda connector power disable, 21-12 
HwExpansionOn 

Honda connector power enable, 21-12 
HwFreeChannel 

free a channel, 21-6 
HwFreeCombo 

free the combo, 21-5 
HwGetBackLight 

get backlight control, 21-7 
HwGetBatData 

return battery information, 21-11 
HwGetChannel 

get a channel, 21-5 
HwGetCombo 

capture the combo, 21-5 
HwGetPsuType 

get power supply type, 21-6 
HwGetScanCodes 

scan the state of all keys, 21-8 


viii 


HwGetSupplyStatus 

get supplies status, 21-6 
HwLcdContrastDelta 

change the LCD contrast, 21-6 
HwNullFrame 

send a serial null frame, 21-4 
HwPacksOff 

switch off the SSDs, 21-1 
HwPacksOn 

switch on the SSDs, 21-1 
HwReadA2Control1 

read Asic2 register 1, 21-2 
HwReadA2Control2 

read Asic2 register 2, 21-3 
HwReadA2Control3 

read Asic2 register 3, 21-4 
HwReadLcdContrast 

read current contrast, 21-7 
HwReLogPacks 

relog the SSDs, 21-11 
HwResetBatteryStatus 

reset the battery status, 21-10 
HwReturnExpansionPortState 

expansion port sense state of, 21-12 


HwReturnTickCount 

tick count - sense current, 21-11 
HwSelectChannel 

select serial channel, 21-4 
HwSetA2Control1 Bits 

setting bits in Asic2 register 1, 21-2 
HwSetA2Control2Bits 

setting bits in Asic2 register 2, 21-2 
HwSetA2Control3Bits 

setting bits in Asic2 register 3, 21-3 
HwSetBackLight 

set backlight control, 21-7 
HwsSetIRPowerLevel 

Set the infrared power level, 21-11 
HwSupplyInfo 

get additional power supply data, 21-10 
HwSupplyWarnings 

get supplies warnings, 21-6 
HwSwitchOff 

switch off service, 21-4 
HwWriteA2Control1 

write Asic2 register 1, 21-2 
HwWriteA2Control2 

write Asic2 register 2, 21-3 
HwWriteA2Control3 

write Asic2 register 3, 21-4 
V/O 


adding a handler, 8-6 
adding an application handler, 8-9 
a synchronous, 8-2 


a synchronous without error reporting, 8-2 


cancel playing back a sound file, 8-13 
cancel recording sound to a file, 8-14 
cancel requested reset, 8-7 

cancel request for a signal from the 
supervisor, 8-11 

chain to root device, 8-3 

chain to super class device, 8-4 
closing a device, 8-8 

enabling a handler, 8-6 


enabling an application handler, 8-10 
getting the shift states, 8-10 
keyboard and mouse, 8-9 
opening a device, 8-7 
opening a unique filename, 9-6 
play back a sound file asynchronously, 8-12 
play back a sound file synchronously, 8-12 
polling for completion, 8-5 
query the completion of IoNextHalfSecond, 
8-12 
reading from a device, 8-8 
record sound to a file synchronously, 8-13 
record sound to file asynchronously, 8-14 
removing a handler, 8-6 
removing an application handler, 8-10 
request a signal the supervisor, 8-11 
requesting reset, 8-7 
request signal on next half second, 8-11 
seeking on a device, 8-8 
signalling completion, 8-5 
signalling completion by pid with no 
re-schedule, 8-5 
signalling completion by process ID, 8-5 
synchronous, 8-3 
wait for completion, 8-4 
wait for completion no handlers, 8-10 
wait for specific completion, 8-4 
writing to a device, 8-8 
1/O system 
messaging, 5-2 
image 
opening to access multiplelibraries, 6-5 
include file 
epocdefs.inc, 1-3 


indextable 

database file, 20-2 
infrared 

set power level, 21-11 
initialize 

the message system, 5-2 
install 

adevice driver, 7-2 
int 

by number, 19-12 
integer 


comparing longs, 13-1 
comparing unsigned longs, 13-2 
conversion to a buffer, 12-1 
divide longs, 13-1 
divide unsigned longs, 13-2 
multiply longs, 13-1 
multiply unsigned longs, 13-2 
of a float, 15-2 
unsigned conversion to a buffer, 12-1 
unsigned long random number, 13-3 
inter process communications 
messaging, 5-1 
interrupt 
calling conventions, 1-1 
capturing, 19-9 
multi service, 1-1 
releasing, 19-10 
single service, 1-1 


INDEX 


interrupts 

alphabetic listing, A-2 

alphabetic listing - extra functions, A-27 

function numbers, A-1 

function numbers - extra functions, A-27 

numerical listing, A-14 

numerical listing - extra functions, A-27 

using single or multi, A-1 
ToAddHandler 

I/O add handler service, 8-6 
IoApplicationAddHandler 

I/O add handler service, 8-9 
ToAsynchronous 

I/O asynchronous service, 8-2 
ToAsynchronousNoError 

I/O asynchronous without error reporting 

service, 8-2 
ToClose 

I/O close a device service, 8-8 
IoEnableApplicationHandler 

1/O enable/disable application handler 

service, 8-10 
IoEnableHandler 

I/O enable/disable handler, 8-6 
IoKeyAndMouseWith Wait 

get keyboard and mouse events service, 8-9 
IoNextHalfSecond 

request completion on the next half second, 

8-11 
ToNextHalfSecondStatus 

query the completion of Io Next Half 

Second, 8-12 
IoOpen 

I/O open a device service, 8-7 
IoPlaySoundA 

play back a sound file asynchronously, 8-12 
IoPlaySoundCancel 

cancel playing back a sound file, 8-13 
ToPlaySoundW 

play back a sound file synchronously, 8-12 
ToRead 

I/O read from a device service, 8-8 
IoRecordSoundA 

record sound to a file asynchronously, 8-14 
IoRecordSoundCancel 

cancel recording sound to a file, 8-14 
IoRecordSoundW 

record sound to a file synchronously, 8-13 
ToRemoveApplicationHandler 

I/O remove application handler service, 

8-10 
ToRequestReset 

I/O request reset service, 8-7 
IoRequestResetCancel 

I/O cancel requested reset service, 8-7 
ToRoot 

I/O chain to root device service, 8-3 
IoSeek 

I/O seek to a new position, 8-8 
ToShiftStates 

I/O get shift states service, 8-10 
ToSignal 

I/O signal completion service, 8-5 


EPOC O/S SYSTEM SERVICES 


IoSignalByPid 
I/O signal completion by process ID service, 
8-5 
IoSignalByPidNoReSched 
I/O signal completion by pid with no 
reschedule service, 8-5 
IoSignalKillAsynchronous 
request signal from supervisor service, 8-11 
IoSignalKillCancel 
cancel signal kill from supervisor service, 
8-11 
IoSuper 
I/O chain to super class device service, 8-4 
ToWaitForSignal 
I/O wait for completion service, 8-4 
IoWaitForSignalNoHandler 
1/O wait for completion with no handlers 
service, 8-10 
ToWaitForStatus 
1/O wait for specific request to complete 
service, 8-4 
IoWithWait 
I/O with wait service, 8-3 
IoWrite 
I/O write to a device service, 8-8 
IoYield 
I/O update status words service, 8-5 
justify 
a buffer, 17-4 
keyboard 
reading, 8-9 
scanning state of all keys, 21-8 
Keyboard 
scan codes HC alphabetic, 21-8 
scan codes HC numeric, 21-9 
scan codes Series 3a, 21-8 
scan codes Workabout, 21-9 
kill 
aprocess, 10-6 
L$X 
environment variable, B-3 
languagecode 
getting, 19-10 
LCD 
getting the type, 19-2 
length 
of a string, 18-4 
LibCopy 
copy data from a categories segment, 6-7 
LibCreate 
creating an object by number service, 6-3 
LibCreateByHandle 
creating an object by handle service, 6-3 
LibDestroy 
destroying an object service, 6-4 
LibEnter 
enter a control region, 6-7 
LibEnterSend 
send message with an enclosing Lib Enter, 
6-5 
LibExactSend 
send message to a known class, 6-5 
LibFind 
dynamic library find service, 6-2 


LibHandle 

dynamic library get handle service, 6-3 
LibLeave 

exit from a control region, 6-7 
LibLink 

dynamic library link service, 6-2 
LibLoad 

dynamic library load service, 6-1 
LibLoadFile 

dynamic library load from multiple library 

file, 6-6 
LibOpen 

open an image file containing multiple 

libraries, 6-5 
library 

opening in an image, 6-5 
library names 

dynamic, 6-1 
LibReClass() 

reclassing an object by number, 6-6 
LibReClassByHandle 

reclassing an object by handle, 6-7 
LibSend 

send message to an object service, 6-4 
LibSendExit 

exit from a method, 6-8 
LibSuperSend 

send message to the objects superclass 

service, 6-4 
LibUnLoad 

dynamic library unload service, 6-2 
link 

a dynamic library, 6-2 
load 

a dynamic library, 6-1 

a logical device driver, 7-3 

a multiple dynamic library, 6-6 

a physical device driver, 7-3 
locate 

a character in a buffer, 17-2 

a character in a buffer folded, 17-2 

a character in a string, 18-3 

a character in a string folded, 18-3 

a character in a string in reverse, 18-3 

a character in a string in reverse folded, 

18-3 
lock 

a memory segment, 2-5 
logarithm 

float function, 15-2 
LongIntCompare 

compare long integers service, 13-1 
LongIntDivide 

long integer divide service, 13-1 
longinteger 

conversion to a buffer, 12-2 

unsigned conversion to a buffer, 12-1 
LongIntMultiply 

long integer multiply service, 13-1 
LongToFloat 

convert signed long to float service, 14-3 
LongUnsignedIntCompare 

compare unsigned long integers service, 

13-2 


LongUnsignedIntDivide 
unsigned long integer divide service, 13-2 
LongUnsignedIntMultiply 
long unsigned integer multiply service, 13-2 
LongUnsignedIntRandom 
unsigned long integer random number 
service, 13-3 
M$0OMO 
environment variable, B-6 
M$IMI 
environment variable, B-6 
M$2M2 
environment variable, B-6 
M$3M3 
environment variable, B-6 
M$4M4 
environment variable, B-6 
M$5M5 
environment variable, B-6 
M$6M6 
environment variable, B-6 
M$7M7 
environment variable, B-6 
M$8M8 
environment variable, B-6 
M$9M9 
environment variable, B-6 
M$V 
environment variable, B-3 
MAIL$ST 
environment variable, B-8 
mark 
resetting the auto switch off timer, 19-15 
match 
a wildcard buffer, 17-3 
a wildcard buffer folded, 17-4 
a wildcard string, 18-2 
a wildcard string folded, 18-2 
media 
read a local device directly, 9-9 
read information of a local device, 9-9 
memory 
adjust heap memory size, 3-2 
adjust the size of a memory segment, 2-6 
allocate heap memory, 3-1 
close a memory segment, 2-4 
copy from a memory segment, 2-7 
copy to a memory segment, 2-6 
create a memory segment, 2-3 
delete a memory segment, 2-4 
find all segments, 2-6 
free heap memory, 3-3 
heap memory dynamics, 3-1 
lock a memory segment, 2-5 
open a memory segment, 2-4 
paragraphs size of, 2-1 
re-allocate heap memory, 3-2 
segment directly accessing, 2-1 
segment locking, 2-1 
segment names, 2-1 
setting the heap granularity, 3-3 
size of available heap memory, 3-3 
size of available segmented memory, 2-2 


INDEX 


size of addressable system ram, 19-6 
size of a heap cell, 3-3 
size of a memory segment, 2-5 
size of RAM disk, 2-7 
unlock a memory segment, 2-5 
message 
enter send, 6-5 
sending to a known class, 6-5 
sending to an object , 6-4 
sending to an objects superclass, 6-4 
message reception 
order of, 5-1 
message system 
I/O system, 5-2 
messages 
asynchronous reception, 5-2 
cancelling receive, 5-3 
cancel request for a signal from the 
supervisor, 5-5 
cancel request for a signal from the 
supervisor by type, 5-6 
freeing, 5-4 
initializing, 5-2 
request a signal the supervisor, 5-5 
sending, 5-3 
sending and getting a reply asynchronously, 
5-4 
sending and waiting for a reply, 5-4 
synchronous reception, 5-3 
messaging 
inter process communication, 5-1 
MessFree 
free message service, 5-4 
MessInit 
initialize messages service, 5-2 
MessReceiveAsynchronous 
receive message asynchronously, 5-2 
MessReceiveCancel 
cancel queued message receive service, 5-3 
MessReceiveWith Wait 
synchronous message reception, 5-3 
MessSend 
send message service, 5-3 
MessSendReceiveAsynchronous 
send message and get reply asynchronously 
service, 5-4 
MessSendReceiveWith Wait 
send message and wait for reply service, 5-4 
MessSignal 
request signal from supervisor service, 5-5 
MessSignalCancelX 
cancel requested signal from Supervisor by 
type service, 5-6 
method 
returning from a method, 6-8, 7-1 
modulo 
float function, 15-3 
month 
abbreviated name of, 11-5 
name of, 11-4 
number of days, 11-4 
mouse 
reading, 8-9 


EPOC O/S SYSTEM SERVICES 


multiply 
two floats, 14-1 
two long integers, 13-1 
two unsigned long integers, 13-2 
name 
validation, 18-5 
names 
device, 7-1 
memory segments, 2-1 
of processes by ID, 10-7 
naturallogarithm 
float function, 15-2 
negate 
floats, 14-2 
notify 
by error number, 19-5 
by text messages, 19-4 
getting state, 19-8 
hooking the interface, 19-5 
setting state, 19-9 
unhooking the interface, 19-6 
number 
getting suffixes text, 19-11 
of week, 11-5 
number of records 
database file, 20-3 
object 
creating by handle, 6-3 
creating by number, 6-3 
destroying, 6-4 
enter a sent message, 6-5 
reclassing by handle, 6-7 
reclassing by number, 6-6 
sending a message, 6-4 
sending a message to a known class, 6-5 
sending a super class message, 6-4 
on events 
receiving, 19-16 
open 
a database file, 20-3 
afile, 8-7 
a memory segment, 2-4 
a multi library file, 6-5 
an I/O device, 8-7 
a physical device driver, 7-1 
a unique filename, 9-6 
operating system 
data segment getting, 19-2 
operating system 
getting the data, 19-3 
operating system text 
getting, 19-8 
owner 
getting, 10-3 
P$D 
environment variable, B-4 
P$F 
environment variable, B-4 
P$IP 
environment variable, B-5 
P$M 
environment variable, B-5 
P$P 
environment variable, B-5 


P$PP 

environment variable, B-5 
P$PX 

environment variable, B-5 
P$S 

environment variable, B-4 
P$SP 

environment variable, B-5 
P$Z 

environment variable, B-5 
panic 

a process, 10-7 

the current process, 10-8 
paragraphs 

size of memory segments, 2-1 
parse 

a filename, 9-2 

generic filename, 19-3 
path 

get current, 9-2 

get current by ID, 9-7 

set current, 9-3 

set initial, 9-8 

test available, 9-3 
PDD 

physical device driver, 7-1 
piezo 

sound, 19-7 
pm 

getting the pm text, 19-11 
polling 

I/O status words, 8-5 
power 

float function, 15-3 
power supply 

getting additional data, 21-10 
priority 

getting, 10-3 

setting, 10-3 
ProcCopyFromByld 

copy data from a process service, 10-8 
ProcCopyToByld 

copy data to a process service, 10-9 
ProcCreate 

create process service, 10-4 
ProcCreateTask 

create task service, 10-4 
processes 

controlling, 10-2 

copying data from by ID, 10-8 

copying data to by ID, 10-9 

copying strings from by ID, 10-9 

creating, 10-4 

find all, 10-7 

get an ID by name, 10-3 

get name by ID, 10-7 

get owner, 10-3 

get priority, 10-3 

get the current process ID, 10-2 

ID and process table, 10-2 

IDs and names, 10-1 

killing, 10-6 

panicking, 10-7 

panicking current, 10-8 


renaming, 10-7 

resuming, 10-5 

scheduling, 10-1 

setpriority, 10-3 

suspending, 10-5 

terminate and kill, 10-2 

terminating, 10-6 

termination registration, 10-6 

watching all exits, 10-8 
ProcFind 

find all processes service, 10-7 
ProcGetOwner 

get the PID of the owning process service, 

10-3 
ProcGetPriority 

get process priority service, 10-3 
ProclId 

get current process ID service, 10-2 
ProcIdByName 

get process ID by name service, 10-3 
ProcIndStringCopyFromByld 

copy a string from a process service, 10-9 
ProcKill 

kill process service, 10-6 
ProcNameByld 

name of a process by ID service, 10-7 
ProcOnTerminate 

register termination service, 10-6 
ProcPanic 

panic current process service, 10-8 
ProcPanicByld 

panic process service, 10-7 
ProcRename 

rename a process service, 10-7 
ProcResume 

resume process service, 10-5 
ProcSetPriority 

set process priority service, 10-3 
ProcSuspend 

suspend process service, 10-5 
ProcTerminate 

terminate process service, 10-6 
Proc WatchAIIExits 

monitor exits service, 10-8 
query 

the number of units, 7-4 
RAM disk 

return size of, 2-7 
random 

float function, 15-3 

unsigned long integer, 13-3 
read 

a DBF descriptive record, 20-7 

a DBF extended header, 20-7 

an absolute DBF record, 20-8 

from a file, 8-8 

from an I/O device, 8-8 

the first DBF record, 20-10 

the last DBF record, 20-10 

the next DBF record, 20-9 

the previous DBF record, 20-9 
reclass 

an object by handle, 6-7 

an object by number, 6-6 


INDEX 


remove 

a device driver, 7-4 
rename 

a file or directory, 9-4 

a process, 10-7 
reset 

I/O cancel request, 8-7 

I/O Request, 8-7 
reset system 

getting the reason for, 19-2 
resume 

a process, 10-5 
re-vectors 

capturing, 19-9 

releasing, 19-10 
S$SVER 

environment variable, B-9 
Scan codes 

HC alphabetic, 21-8 

HC numeric, 21-9 

Series 3a, 21-8 

Workabout, 21-9 
seek 

a file to a new position, 8-8 
SegAdjustSize 

adjust the size of a memory segment, 2-6 
SegClose 

close memory segment service, 2-4 
SegCloseLockedOrDevice 

close a locked or device segment, 2-5 
SegCopyFrom 

copy from memory segment service, 2-7 
SegCopyTo 

copyto memory segment service, 2-6 
SegCreate 

create memory segment service, 2-3 
SegDelete 

delete memory segment service, 2-4 
SegFind 

find all segments service, 2-6 
SegFreeMemory 

size of available segmented memory, 2-2 
SegLock 

lock memory segment service, 2-5 
segment 

change size of a memory segment, 2-6 

close a memory segment, 2-4 

close locked or device, 2-5 

copy from a memory segment, 2-7 

copy to a memory segment, 2-6 

create a memory segment, 2-3 

delete a memory segment, 2-4 

directly accessing, 2-1 

find all segments, 2-6 

lock a memory segment, 2-5 

locking, 2-1 

names, 2-1 

size of available segmented memory, 2-2 

size of a memory segment, 2-5 

unlock a memory segment, 2-5 
SegOpen 

open memory segment service, 2-4 
SegRamDiskUsed 

size of RAM disk service, 2-7 


xiii 


EPOC O/S SYSTEM SERVICES 


SegSize 

size of memory segment service, 2-5 
SegUnLock 

unlock memory segment service, 2-5 
semaphores 

creating, 4-1 

deleting, 4-1 

signalling once without re-schedule, 4-2 

signalling more than once, 4-2 

signalling once, 4-2 

waiting, 4-1 
SemCreate 

create semaphore service, 4-1 
SemDelete 

delete semaphore, 4-1 
SemSignal 

signal once service, 4-2 
SemSignalMany 

signal many service, 4-2 
SemSignalOnceNoResched 

signal once with no re-schedule, 4-2 
SemWait 

wait on semaphore service, 4-1 
send 

a message, 5-3 

and get reply asynchronously, 5-4 

and wait for reply, 5-4 
sense 

an absolute DBF record, 20-9 

the current DBF record number, 20-13 
shiftstates 

Getting, 8-10 
signal 

a semaphore once without re-schedule, 4-2 

a semaphore more than once, 4-2 

a semaphore once, 4-2 

from the supervisor, 5-5 

from the supervisor I/O , 8-11 

1/O completion, 8-5 

1/O completion by pid with no re-schedule, 

8-5 

1/O completion by process ID, 8-5 
SignedIntToFloat 

convert signed integer to float service, 14-3 
sine 

float function, 15-3 
size 

a database file, 20-6 

of addressable systemRAM, 19-6 

of a memory segment, 2-5 

of a string, 18-4 

of systemram, 19-6 
sleep 

a process in system clock ticks, 11-2 

a process in tenths of a second, 11-2 

a process till a given time, 11-1 
sound 

cancel playing back file, 8-13 

cancel recording to file, 8-14 

getting the flags, 19-7 

play back file (partial) asynchronously, 8-15 

play back file asynchronously, 8-12 

play back file synchronously, 8-12 

record to file asynchronously, 8-14 


record to file synchronously, 8-13 
setting the flags, 19-7 
using the piezo, 19-7 
Sound 
Pitch calculating, 19-7 
Sound file names 
Series 3a ROM, 8-12 
sound files 
format .wve files, 8-1 
SP$DRV 
environment variable, B-7 
SP$OPT 
environment variable, B-7 
square root 
float function, 15-4 
SSD 
relog, 21-11 
status 
of a device, 9-5 
of a file or directory, 9-4 
of a file system, 9-5 
string 
capitalising, 18-1 
comparing, 18-1 
comparing folded, 18-2 
conversion to float, 12-5 
conversion to folded, 18-1 
conversion to integer, 12-3 
conversion to long integer, 12-3 
conversion to unsigned integer, 12-2 
conversion to unsigned long integer, 12-2 
copying, 18-1 
copying folded, 18-1 
length, 18-4 
locating, 18-3 
locating folded, 18-3 
locating in reverse, 18-3 
locating in reverse folded, 18-3 
substring, 18-4 
substring folded, 18-4 
validate, 18-5 
wildcard match, 18-2 
wildcard match folded, 18-2 
StringCapitalise 
convert a string to have the first letter 
uppercase and the rest lowercase service, 
18-1 
StringCompare 
comparestrings service, 18-1 
StringCompareFolded 
compare strings folded service, 18-2 
StringConvertToFolded 
convert string to folded service, 18-1 
StringCopy 
copy string service, 18-1 
StringCopyFolded 
copy string folded service, 18-1 
StringLength 
length of string service, 18-4 
StringLocate 
locate a character in string service, 18-3 
StringLocateFolded 
locate a character in string folded service, 
18-3 


StringLocateInReverse 
locate a character in a string in reverse 
service, 18-3 
StringLocateInReverseFolded 
locate a character in string in reverse folded 
service, 18-3 
StringMatch 
match a wild card string service, 18-2 
StringMatchFolded 
match a wild card string folded service, 
18-2 
StringSubString 
find a substring in a string service, 18-4 
StringSubStringFolded 
find a substring in a string folded service, 
18-4 
String ValidateName 
validate a system name, 18-5 
structures 
SupplyInfoEnt, 21-11 
sub- buffer 
in a buffer, 17-3 
in a buffer folded, 17-3 
substring 
in a string, 18-4 
in a string folded, 18-4 
subtract 
floats, 14-2 
suffix 
getting text, 19-11 
SupplyInfoEnt 
Data structure, 21-10 
structure, 21-11 
suspend 
a process, 10-5 
swap 
two buffers, 17-1 
switching off 
disable/enable if mains present, 19-16 
get state if mains present, 19-16 
switching on 
reporting, 19-16 
synchronous 
V/O , 8-3 
message reception, 5-3 
tangent 
float function, 15-4 
tasks 
creating, 10-4 
terminate 
a process, 10-6 
termination 
registration, 10-6 
text 
getting operating system, 19-8 
tick count 
sense current, 21-11 
tickle 
resetting the autoswitch off timer, 19-15 
TimDateToDaySeconds 
convert date to day seconds service, 11-3 
TimDayOfWeek 
day of week service, 11-4 


INDEX 


TimDaySecondsToDate 
convert day seconds to date service, 11-3 
TimDaySecondsToSystemTime 
convert day seconds to system time service, 
11-3 
TimDaysInMonth 
days in month service, 11-4 
time 
convert date to day seconds, 11-3 
convert day seconds to date, 11-3 
convert day seconds to system time, 11-3 
convert the system time to day seconds, 
11-3 
getting the system time, 11-2 
setting the system time, 11-2 
sleeping for system clock ticks, 11-2 
sleeping for tenths of a second, 11-2 
waiting till a given time, 11-1 


times 

absolute and relative, 11-1 
TimGetSystemTime 

get the system time service, 11-2 
TimNameOfDay 

name of day service, 11-4 
TimNameOfDayAbb 

abbreviated name of day service, 11-5 
TimNameOfMonth 

name of month service, 11-4 
TimNameOfMonthAbb 

abbreviated name of month service, 11-5 
TimSetSystemTime 

set the system time service, 11-2 
TimSleepForTenths 

sleep for tenths of a second service, 11-2 
TimSleepForTicks 


sleep for system clock ticks service, 11-2 
TimSystemTimeToDaySeconds 
convert the system time to day seconds 
service, 11-3 
TimWaitAbsolute 
wait till a given time service, 11-1 
TimWeekNumber 
week number service, 11-5 
trash 
a DBF buffer, 20-4 
TW$S 
environment variable, B-6 
unload 
a dynamic library, 6-2 
unlock 
a memory segment, 2-5 
UnsignedIntToFloat 
convert unsigned integer to float service, 
14-3 
update 
a DBF record, 20-11 
validate 
a string, 18-5 
vectors 
calling, 7-5 
version 
of the ROM, 19-1 
operating system, 19-1 
the DBF version number, 20-8 


EPOC O/S SYSTEM SERVICES 


W$C 
environment variable, B-7 
W$R 
environment variable, B-7 
wait 
an I/O completion, 8-4 
an I/O completion no handlers, 8-10 
a process till a given time, 11-1 
a specific I/O completion, 8-4 
on a semaphore, 4-1 
watch 
all exits, 10-8 
week 
number, 11-5 
wildcard 
buffer match, 17-3 
buffer match folded, 17-4 
string match, 18-2 
string match folded, 18-2 
WP$SPEL 
environment variable, B-7 
WPS$THES 
environment variable, B-7 
write 
a DBF descriptive record, 20-8 
a DBF extended header, 20-7 
to a file, 8-8 
to an I/O device, 8-8 
WVE sound files 
format, 8-1