SIBO 'C' Software Development Kit EPOC O/S SYSTEM SERVICES Version 2.30 March 1, 1999 (C) Copyright Psion PLC 1990-98 All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC, London, England. Reproduction in whole or in part, including utilization in machines capable of reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse engineering is also prohibited. The information in this document is subject to change without notice. Psion and the Psion logo are registered trademarks, and Psion, Psion MC, Psion HC, Psion Series 3, Psion Series 3s, Psion Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of Psion PLC. Intel 8086 and 80286 are registered trademarks of Intel Corporation. IBM, IBM XT and IBM AT are registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. Psion PLC acknowledges that some other names referred to are registered trademarks. CONTENTS DTG OGuiC ts, isi eccci ss ce casisccctesecedeccsnccsstcsscodeccseecedesdecsdeccdececesssscedsccsnecstecdscedeccsssececedecedecessecestes Ld SYSCEMM SEL VICES oi heh: suk veloeehs gcbedua vudewes saebeduh ods conte cebede pub coves cousvah edtbewstocebebenedtigweseeuhienonst Single service:interrupts ::.43:8Ascniiao sss ob de adehl Adenine s Ag Multi Service titerrupts's.esic.s3isstecstuts Seeeduveteossets Seeded sduvsesbaduesduysdeusteda dice dubsduectedsdyvadevednes dS Gallin S COMVENHONS .i5.45iudssvcsasaciasetaaseeest dash svandasatea io cananthzestaasapeanaoasgestessanessaashosetaswetess Documentation conventions Include file epocdefs.inc 2 Segmented Memory Management ...............ccsscccsssssscsscsscssscsecssccsesssscscesssscssesssccscsssssssesssscssees DOL Memory Segment naimes::i.ci:4cc.tistscssdaicesnigthosndshecetintiosnads ht eetdathesnnda beeetgatbosadaitiestdabas Paras raps ns. cic; sh. chchcs cobs seeks dokcces Sees gua hacetcaes cous euch sdeewes cqunguske ocd ede Suvsgunbeces eoes Syuagunnecedetes boue Permanent se@iments so: i.c508 Viste hab aihisien es Asians Aaehilen Sai ache Directlyaccessin g: S6SiMeNts sai. et sakess aaches cessdieseeva deesecssduessscadeesecbideostetaceeedusadevssdyvedetaluneds Size of available segmented MEMOTY ...........c ce eeseeeeseeesseecsseecesseeesseecsaeecscesseecesaeeesaeeesaeers Creating a memory segment Deleting a memory segment Opening a memory segment % ClosinS:a;memory Seement 5: .12:.3:5:45..1daisoeesacsvodendaiscsssactasseadaustestaacassendateaetaatassndaseasseaiay Closing a locked or device SCQMENE........ eee eeseeeeseeeesneeesneecseecsseecesaeecsaeersaeeseneeeesaeeesaeers Locking a MeMOFy SCYMENL........ eee eeeececeeseeceeeeseeececeeeeeeeseaeeecsesneeeceeeeeesseaeeeeeeseeeeeeaees Unlocking a MeMOTY SCYMENL «ue eee eeeeceseeeeseeeseecseecseeceseecesaeecseaeessneeeetaeeeseeesaeers Size‘of A MeEMOory SESMENE: s355:cisscsiszcssdalssesteseapesidsnscestegnapeahastsrestadsapeandgasoeedeass deusacenouetadase Adjusting the size of a memory segment Finding all s@ornents o.xisc3 4. oscek desedass doavices covudanscesvideatsazssveedata ds sadunacvas seach stbaaarete sade aobeaares Copying to a MEMOTY SCYMENE ........ ee eeeeeeeeeceseeeeseeesseecseecscecsseecesaeessaeecseessseaeeesseeesaeers Copying from a MEMOTY SEZMEN....... eee eeeeeseeesseeeeseeeceeecseeceseeeesaeecsaeessaeeseseeeesaeessaeers Size OP RAM disk s:. cu ssisea shi neler ed adiaoki ded casi ne ole ciel 3 Heap Memory Management ...............ccccscccsscssscssscssecssscscecsscsscsssscssccssccsesssscssscsssscssessssssessssees OU Dynamics:Of hedp mem Ory: i.5 ess.2¢ssco0s hes feist ss cog danheeevdsbestieatas, Hee easebalin fos chesdeystheed 3-1 Allocating heap MEMOrys: .sc..iisBesstsaticestiahassitascessataocsidaatgesbeedateuensealeatieostosungeaseatheestans 3-1 Re-allocating heap MeCMOTY.............seccesssecsssceesseeceseeeesseecsaeecseecsseesesseeesaeesseeseneeeeseeeenaes 3-2 Adjusting the size of heap MeEMOTY................secesecceseceeseeeesscecesceceseeceseeeesacecssnecsseeseseeeeners 3-2 Freeéms heap Memory x .2. 5:0. eck. codsdavssta davis coisteszdes Sbvke eedazeosdeu ubke fubadevsdon Stbbe peaduuaion aheaelo2es 3-3 Size’of a:heap, cells: scssstsiavicisseslascsadaseassea lace aadacieastesiaocandacdeasteaaoeaniaisoasteaiaoeasacboesteayse 3-3 Setting the heap: sranularity «nsec scadneciodtas ou nelendidshasio ied ost glibelsieveess 3-3 Size.of available heap Memory 25:52:35.5 fos: ase sbereedash aaedesdeaediesnd assdiadeendasiansyiaonseeths 3-3 4 Semaphore Management ..............cccssssccsscssscssccsecssccssscscesssscsessssccsccscscsssscsesssscsseessscssssscessess Ged Creating a semaphores. :ci2issccanschasiehis itt eedatiosatdadcsaacstaneaneatieassboeadiodgdelesteoeaiguavenetas tees 4-1 Deleting a semaphore.............cecccceeesscceessnceeceeeneeecesceeceeeneeeceseeeceseeeeeeseaeeeeeseeeseneaeeeseeanees 4-1 Waiting on a Semaphore..........e.ccceseecccesssceeceeesseeeceeneeeeceeaeeeeseeeeecesnneeesseaeeeeeseaeeeeeenneeeeeeee 4-1 Sie tall SON Ce ees’ ivis 505 seh eek Sees ects aes ted saves eed deve ee does eat Fee teasoeks dubs Sealed te Geese thy 4-2 Signalling More than Once s....::ssctedsiesteaiateatlaeetesiscsatledsetensteetlidostasecentlaoeteaeiens 4-2 Signalling once without re-schedule......... eee eeseesscecsseecsseecesseessaeecsaeecseecsseecesaeeesaeeesaeers 4-2 March 1, 1999 EPOC O/S SYSTEM SERVICES 5 Message Management ...............ccccccsssssssccsssccccsscceeccssssscsssceseccssscscecsseesccsssccsssessssssssscsssseeesssssees 5-1 Inter process COMMUNICATION ............:ceeeeeeeceeeeneeeeeeeeceeeeeeeeeeeeneececeeenaeeeseeeeeeeseaeeeseenneeeeeeas 5-1 Order of Message TECEPLION ice ciccciseeicveisetdccoigerdceeseenccevsdandeevedeaseesddaalesuedebdesuddesdeeidenisanecs 5-1 The message system and the I/O system .............cessccceeeessceceesceeeeeeeeecesseeeeessneeceseaeeeeseaees 5-2 Initializing the message SYSteM ............:cceeecseeessseceeeeeeeeeeeeeeeeeeeaeeeeeseaeeeeeenaeeeeseneeeeentaeeeees 5-2 Asynchronous message reception ...........::ccceeecceeesseceeeeeeeeceseeeecensaeeeceseaeeeeeeaeeeeensaeeeeseanees 5-2 Synchronous message reCeptiOn............csccceeeescccessseceeeeenceeeeeeeeeceenaeeecsseeeeeseeeecesteeeeeenees 5-3 Cancelling queued message reCeive ...........cceeccceeeesceceeenececeeeneeeeseaeeeeeseaeeecseeeeesesaeeeeeenees 5-3 Senin S MESSAGES... usdescesesesvetacsceuevas deveiuade ces scan cose dcanccvu cena dev deaacenvedaa Ooaucedascuccnaevandeneevandes 5-3 Sending and getting a reply asynchromouslLy ..............:::cccesecceeeeesceeeeeeneeeceeeneeeessnneeeeeeeeeess 5-4 Sending and waiting for a reply..........ececccceessccceceeeeeceeceenceceeseneeecesnneeecseeeeeeenaeeeeseneeeeeeeee 5-4 FTGCii SA MeSSAGe aia ass ree aeons eeags Saves See Uelet ash Sail eae asOutess caved exe sbuutads Cousleseedlabeds cust eesescteseuals 5-4 Requesting a signal from the SUpervisOL............:c::cccessseceeesenceeeeeeneeeeeeneeceeeeeeeeeseaeeeeeenees 5-5 Cancelling requested signal from the Supervisor .............cccesecceeesenceeeeeseeeeeeeneeeeeenneeeeeeaeees 5-5 Cancelling requested signal from the Supervisor by type ...........::::cceseesseceeeseeeeeeeteeeeeenees 5-6 6 Dynamic Library, Category and Object Management...............ccccsssccssssssccsscsecsssseessssceeeeees 6-1 Pabrary Names 5 iss scaisesescatsseusta heels tas itatienatlalieentaaectlaieenitataelbatiec ts tecatis teats tates 6-1 Loading a dymamic library............cecesccecessccceeesneeeeeseeeeecsenneeeeeeaeeeceenneeesesaeeeeeseneeeseenneeeeneas 6-1 Unloading a dynamic library ...........ccccccceeeeccceessncceeeesaeeeeeseneeeceeeeeceseaeeeeessneeeessneeeeeeneeeess 6-2 Banikanig 4 dyinarnie MaDrary cues sic: ese we cevs iuadevs ca vaces dana devs cana covtaiia tuvtalvecavhdin ofutteaeveest da ceaase 6-2 Getting a dynamic library handle ............eeeccceceeecceeeeneceeesneeeeeeseeeeeeeneeeeeenneecessneeeeeneeeeess 6-2 Getting a DYL handle by numbe’............... ce eeecccceseccceeeeneeeeeeeneeceeeneeeeeseaeeeeeseaeeessenneeeseees 6-3 Creating an object by mUMber ............ceecccceeesccecesneeeceseneeeceeeeeecessaeeeeesnaeeeeeseeeeeneaeeeeeenees 6-3 Creating an object by handle .0..........eeeecccceescccecssnececeesneeecesneecessaeeecessaeeecseneeeseseeeesenees 6-3 Destroyii ean, ObjECte: iceitazssssusdasesstislacoutaadosetes aosendarsncatealaasntaaoesigasaeundasoeateniagcandateee? 6-4 SemMGIMS a MESSAGE a5 5 coca se voctek Sesedes Sewsatehs gveanen cqusatetegenetancnonetenaunenen oeveemens dubecen puvedeensintett 6-4 Sending a superclass MeSSAage...........ccseccccesseceeessnececeeeeeeceeneececseeeeeeseaeeeeesneeeceeseeaeeeeseanees 6-4 Sending a direct MesSAGe ies vss ks se. seekeseese Na syen cubase ese based cuvtoyeceavasyun cova dyede cds Fyekdeveaneeces ieee 6-5 EMiter: a; SNE MESSAGE ssicccsssvasevuecasceekegesdaanecaacousad sag ootadaadecassuagennaaesdenssdvapeatesuaGayssaueseaseecatads 6-5 Open a multi library file... eee eeeeccceessceeceeneeeeeeeneeeceeneeeeesneeesseaeeeceeeaeeeensneeeeeneaeeeess 6-5 Loading a multiple dynamic library..............ccceeecscceeescceeeeeneceeeceseneeeeeseeeeeseaeeecesnnseeeseanees 6-6 Reclass an object by NUMDED ...............ceeeccceeesnceeeesneeeceeeneeecesneeeensaeeeessnaeeeesseeeeeneaeeeeneaaees 6-6 Reéclass‘anobject by Wandle v2.3: vssscsiassudetowsteslassentavsneataaiarcutasaverigsincecandanseearagiateardarsee cd 6-7 Copying data from a Cate QOry........escccceessccceeesnsceceeeeeeeeeseeeeeeeaeeeceseeeeeeeaeeeeseeaaaeeeseenneeeeeees 6-7 Enter a:control Tést0ns, toes. dete hathiacdets a Bdeoiatdenaci edo deed titi lt 6-7 Lea vitte a 'COntrol’ Te G1 OM )c225 esi ces Fees Beiet wes 08 hea 00aGa wes Syus Daete sec S aah ue (Seta eee 0a yen SeeS Ryka Ts danse 6-7 Returning from a method. ...........ccccceeesscceeeseeeeeencecceeeaeeeceseceecesseeecsenaeeeessneeeeesseeeesenees 6-8 7 Device Managemen ............ccsscscccsscsssccsscssccssscscesssccscessscscesssscscssssssessssscsesssscssesssssesssssesesessees 7-1 TIEVICETIAIMES 602. Aosed sets out te ooes oats arcutieds oobertiAdenetedeticne dea sciotedoteboveck eonttedecuavedscctetedomdssecoee 7-1 TJOVICE=ATI VETS o35 osteo ebes eee ce eae ea oe aio ok oe An oo Sls ON ot ies 7-1 Opening a physical device Ariver......... eee seesecceseecesceeseecseecseecsseesesaeeesaeessaeesseeesseeeesaes 7-1 Getting the PDD entry point... ee eeeeeesecsseeeeseeeesseecsaeecsscecseecesaeeesaeecsaeecseeseseeeesaes 7-2 Installing a device Ariver ...........ccceeceescceceesecceeesneeeceesneeeceeeeeceseaeeeeseeeeeeeeaeeeesseneeeesenneeeeeees 7-2 Holding all device Arivers............ccceesscccceescceeeencecceeseeeecseeeceeseaeeecesneeeeeseeeeeeenneeeseenneeeeeeae 7-2 Resuming all device Arivers.........e ee eeseesseecssceesseeceseeeesseecsseecscecsseecesseeesaeecsaeesseeseseeeenaes 7-3 Loading a logical device Criver wi... eee ceeeeeesseeesneecssceceseecesaeecsaeecsacecseecsseeeesaeessaeessneeeeee 7-3 Loading a physical device river .........e sc eeeceeeseeesneeceseecsseecesaeecsaeecsacecseecseeeeesaeessaeesseeeees 7-3 Deleting: a device driver. c.csss. coseeigeiydik ogcestegisdesh be pheek eenadi gies Hesaylesbedenaghdesupbeseeeyeeideges 7-3 Removing a device Ariver ............ccsscccceessceceeseceecesncecessaececessneecessaneeceseasesesuneesessaseeeseanees 7-4 Querying the number Of Units ..0........ ce eeecccceeecccecesnececessneeeceseeeceneaeeeeeseaeeeeeseeeeeeeaeeeeseaees 7-4 Finding all AG ViCesrs.3 2. ccccs cceseastc dovesntedsgotaue te sadetebesadaue dedaceh odes atseavevedes sdaselesscigentdgetesetlannises 7-4 Callinga device vector ....s:taiiiet seiideieesteiebe dete piestdivdesdetepies dade debehi pda deseideeneaanegnls 7-5 CONTENTS 8 Input Output Management ................ccccscccssssssccsscssecssscsecssscsseessscscecssssssssssscsesssscssesssscsssssscesoes 8-1 Devices anid HES fics ccieiy sioee eis tegs te sitea tie seen Sete sdata iig step ody scenadee sauce dey sdehe eset tevsene a ested 8-1 Sound ‘file format: states cain Peak pa la pin la ibaeiaobehed 8-1 ASYNCHrONOUS T/O so seb os San Soes oh do beeak aie 0aY, DSc Dae se I eh Nl oes aoa aa ote ee eh Po oak 8-2 Asynchronous I/O without error repOrting.........eeeeeeeseeeeseeseneeceseeeesaeecsneessaeessneeeesatessaeers 8-2 SVNCHLONOUS: LO sees su. osasiedes oxdgstescvepedesbes pbanbeonpeds betes asubees bode Gedepbunteen dedessduprantersdedes sdevauesered 8-3 Chainto root device ss..s:.cccsceinege sis abe nest edipaee antes ech paive died beeyaens oyeel begindenk epee easy 8-3 Chain, to‘superclass devices. a.tiec 58 cithediteet ah aided at as oh steel eb i a ee ema 8-4 Wait for I/O completion .0...... cee eeeeeeseecsscecsseeesseecesaeecsseecsseecseecsseecesaeeesaeessaeesseessneeeesaes 8-4 Wait for specific request to Complete ........... eee eeseeesseeceseecesceeesseecsaeecseeceseeeesaeessaeessaeeeens 8-4 Polling: for completion: .2..s:2 atee.i- Bytes hie agate belddoyiested bee depoeniann el egevienbeaadeiess 8-5 Signalling Completion .................:::csesecsesessoreresseesonenecsonevessenensenensetenseesnonersonevenseneneetenseess 8-5 Signalling completion by process ID ........eeseeesesescecsseeceseeeeseeeesseecsseesseeceeesesaesesaeessaeers 8-5 Signalling completion with no reschedule ............escceeccessseeesneeceneeeeseeeeesaeecsaeecsseeeeseeeesaes 8-5 Adding a handler: sic.e-ssc.g peeiteg.yotegigih teh voewncg geese vovead pees eye dagen Testo egapee eee ey 8-6 Remiovin & a Wan letsy cx 22 sce ccictiec sek suit cesitest shat octastonk sitter tyst cas ul earache tant sees 8-6 Enabling a handlets..2::s.vaiewli ncteientedi vinnie tau etal nas alaiewigsataucare. 8-6 Requestie sa: Feset sess a cess Sil, tar feg ales Rueevet vey dations seat gales Sug eestadeyodeneeerewateddvede Suupvaxtees: 8-7 Cancelling: a requested reset. .:.: s.vos.osa.pduet eisdelbegipaed Gade dedi plaid des esegapdaneedeyeldaeepiebenedees 8-7 OPpeNiN Sa GEVICE: wocczten 2. eheak Toeet oes it eet oe ER eek oO a ae at ce a en Sak 8-7 Closing a:dévices: sicistec hil ei navi ev a ee eee 8-8 Reading from a CeVICC...... eee eeseeceseecesseecseecseecsseeeesaeecsaeecsseecsseecesaeecsaeesseessneeeesatessaeers 8-8 Writing toa deVICE 2.205552 Gaye suesiytank epee aanvdonk Geipeekbeeap dees ath eaaedesd depeeldusaeoestdephibesnee eee 8-8 SEEKING OF: a GEVICE so es hos She the et oho cata See abot cats Siet ok abcd ast tant cos heteroatoms Gestetvint sae? 8-8 Mouse and keyboard 2:3 s.ve:.ates cava tales ee aith ian ceaieieieiiniausndgaaieicey 8-9 Adding an application handler ........ eee eeeseecsseeceseeeesseecsscecsseecsseecesaeecsaeecsaeesseeesseeeesaes 8-9 Removing an application handler ......... eee eeeeeseeesseeceseecsseecseeceseeeesaeeesaeecsaeesseeseseeeesaes 8-10 Enabling an application handler... eee esceeeseecsseeeeeeeesseesseeceseecesaeeesaeecsaeessneeesseeessaes 8-10 Getting theishift’states..:::..c4.c.css hs ties cel iin laren bk inn ainn linn nea 8-10 Wait for I/O completion no handlers 20.0.0... eeeeeseeescecsseecesseeesseecscesaeecsseeesseeeesaeeesneeeaee 8-10 Requesting a signal from the SUperViSOL...........:::ssccssecesseessseecsseecsseeceeeceseeessaeecsaeerseeenees 8-11 Cancelling requested signal from the Supervisor ............c:ccessssceceeseecsneecsseessteecneeesseeeesaes 8-11 Request signal on next half secondo... eeeeeeeseecseessneecseecseeceseeeesseesaeeesaeessaeeseneeeesaeen 8-11 Query the completion of IoNextHalfSecond ....... cee eeeeeseecsseeceseeeeseecsaeecseesaeessseeesseeeesaes 8-12 Playing back a sound file synChromousSly.............essesessseeeeseecsscecsseecneeceseeeesaeecsaeecseesnnees 8-12 Playing back a sound file asynChronousSly............esecseseceseecsseeesseeeesaeecseesneecsaeecseeeeseeeesaes 8-12 Cancelling playing back a sound file oo... eee eeeseeceecesseecseecsceceseeeeseeeseeeesaeecsaeesseeesnees 8-13 Recording sound to file synchronously ............cceseceseseeesseeeescessseeseecscecesaeeesaeecsaeesaeeesaeers 8-13 Recording sound to file asynChronously............cceecesssecesseessseecssceceseesseeceseeeesaeecsaeesseeeaeers 8-14 Cancelling recording sound to a file... eee eeeeesceseessseecseecsceceseeceeeceseeeesaeecsaeesseeesnees 8-14 Input Output Management update 0.0... eee eeeeeseeceeneeceeecsscecsseeeesaeecsaeesseecssaeeesaeessaeers 8-15 Asynchronous partial sound file replay .........ceeeeeceeeseeceneessseeceeeeeesseecsseecsaeeseseeeesaes 8-15 D File: Manageme nt sccccicecsescicecstccssecsasseosssessasesbaséosesencsosusenssocvsaddsoeebsedsonsbeddsondnsassseeensesoavonssseases 9-1 TRE ALE: SOR VEL, sas s2ich coset iss 522s Seve ta bos cck Fibs feist basen Big Pete Ses ovd Rana voevd ba Aes cvd Saeanetes 9-1 Connecting to the file‘serverssissieacstdss.cs.istsceatdsascastisioeatasssass testes atabasoeeleateaeataiaaselas eens 9-1 Execute-an amie tiles cscs aul sie Gulia ie A Be eels 9-1 Parse-a-file name is: ssthess deste Asvtitehivtins Anoisbe Ash. ns Aaphesichepions Aativascup cassislaamiers Aneaisins 9-2 Get Current Path ss sss. cers sieccck siunecudtauis seb saues cvssecbs dub sevbs rodbarie feb sanyesevechvededsteeesesetevesvescevesvecdes 9-2 Set current: Paths icecs.ssguscscadesesesscesssesseaseoohesascesseaisesbesasseredsassostesendsoddsavevets desssetdsassoata suey 9-3 Test Path: available si: 265. scchSsegesue ces seehs dckewus cess ceebosehesus Sesetues dele sea ravbevelosesevtacisl Seresbeveasaeh od 9-3 Deléting:a filer ditectOry...si.:sis,oah sinew alain oun danse ek Baaie A 9-3 Renaming a file:or directory. sic csss2h oxsevs thus Pesach ws eoes ch sstadeuseusacieosdubeeets buastbethessshackencudstanedy 9-4 Getting file or directory, Status: :i.:sic:.ce.iishspeciesi.cestestageatasisceteaiapeasensoesles at easaceionelaseseees 9-4 Setting file or GirectOry Status................:csesesseresesereneeteneeecsonerssevensetenseessonertsevensetenseees 9-4 Getting: device status. ic. s. levis syiekeseedastvsvdasiseedsaesbeascssadisesvaghuse ovsidessdvasdes usibereserdios se 9-5 Gettinig’ file System Status... :r03>= 1E+100. UnderflowErr Float << 1E-99. PANIC: None Converts a double floating point number in [SI] to a printable ASCII zero terminated string pointed to by DI using the supplied format specification. The format specification is contained in the ptobEnt structure as defined in epocdefs.inc as: Dtob struc ; dtob format string structure DtobType db ? j conversion type DtobWidth db DtobNdec db DtobPoint db DtobTriad db DtobTrilen db ; threshold for triad character use DtobEnt ends ; width of representation in characters ; number of decimal places ; decimal point character ; triad separator character VN VV Vy Numbers may be represented in various formats by setting ptobType as follows:- @ DtobTypeFixed, fixed point format. @ DtobTypeExponent, exponent format. @ DtobTypeGeneral, general format. Integer format is obtained as a special case of fixed point format where the number of decimal places required is zero. The parameter [DX].pt obwidth specifies the maximum number of characters allowed to represent the number and there should be [DX].pt obwidth+1 bytes (the +1 is for the zero terminator) reserved at DI. If the output exceeds this limit, railzrr is returned. Although numbers are normally displayed right-aligned, convFloat ToBuffer makes no attempt to align the result in the buffer. Alignment is quite different for monospaced and proportionally spaced character fonts and is best handled by post- processing the output from convFloatToBuffer. [DX].pt obwidth should be in the range | to 255 inclusive. The parameter [DX].ptobNdec specifies the number of decimal digits following the decimal point when [DX].pDtobType 1S DtobTypeFixed OF DtobTypeExponent. [DX].ptobNdec must be in the range 0 to FloatSignificantDigits (15 for IEEE floating point format) inclusive. The parameter [DX].ptobPoint specifies the decimal point character which separates the integer portion from the fractional portion and would normally be either a'.' or a',’ . The parameter [DX].pt obTriad specifies the triad separator character which delimits groups of 3 digits in the integer part of the fixed point representation and would normally be either ',’ or '.' or '' . The insertion of triad separation characters is disabled if [DX].ptobTrilen is 0 and otherwise enabled when the integer portion of the number contains greater than [DX].ptobTrilen digits. Normally one would use [DX].ptobTrilen=1 to enable triad separation and [DX].ptobTrilen is 4 to conform to French conventions for triad separator insertion. In all cases, negative numbers are represented by the insertion of a leading '-' sign (positive numbers do not have a leading '+' sign). This can easily be post-processed to obtain a bracketed representation of negative numbers, if desired. There can never be more than FloatSignificantDigits(15 FOR IEEE floating point format). Where there are less than FloatSignificantDigits, the number is rounded to the number of significant digits displayed. 12-4 12 CONVERSION MANAGEMENT The limitation to floats with magnitude between 1E-99 and 1E+100 results from the use of lookup tables for speedily generating the results. Floating point numbers of magnitude smaller than 1E-99 can easily be converted to 0 before calling this service. The detailed formatting details as a function of [DX].ptobtType is as follows: @ DtobTypeFixed - The number is represented with [DX].pt obNdec decimal places where [DX].pt obNdec may be zero to represent an integer (in which case no decimal point character is displayed). If the ASCII form exceeds [DX].pt opbwidth (usually due to the number being large and having too many digits before the decimal point), railzrr is returned. A zero is displayed in the form "0.000" where there are [DX].pt obNdec zeros following the decimal point or as just "0" if [DX].DtobNdec is zero. @ DtobTypeExponent - The number is represented in exponent notation with one non-zero digit before the decimal point and [DX].pt obNdec digits beyond the decimal point followed by 'E', a sign ('+' or '-') and the exponent as two digits (with leading zero if necessary). If [DX].ptobNdec is zero, the number is rounded to one digit of precision and no decimal point is displayed. A zero is displayed in the form "0.000E+00" where there are [DX].pt obNdec zeros following the decimal point or as "OE+00" if [DX].ptobNdec is zero. Triad separation is not available and triad separation parameters are ignored. @ DtobTypeGeneral - converts either as fixed format (with no triad separator) or exponent format, making best use of [DX].ptobwidth. Here, "making best use" is defined as showing the greater number of significant digits and preferring fixed format when the number of significant digits shown is the same. The number of decimal places is chosen as a function of [DX].ptobwidth and the value of [DX].pt obNdec is ignored. A zero is displayed as just "0". Triad separation is not available and triad separation parameters are ignored. ConvStringToFloat String to float SI address of pointer to text to convert Dx Decimal point character DI Pointer to double destination RETURN: Carry clear Success RETURN: = Carry set FailErr Failed to recognise a number. OverflowErr Number too large. UnderflowErr Number less than 1E-99, 0 written to [DI]. PANIC: None Scans the string for a number and writes the value as a double float to [DI]. If underflow occurs, zero is written to [DI]. The supplied ASCTI string should take the form: [+|-]<.[E|e] [+|-]<> Where: e = The leading '+' sign may be omitted for positive numbers. <> and <> are optional but at least one should be present. e Leading zeros in are legal but have no effect. e = Trailing zeros in are legal but have no effect. e = There is no reasonable limit to the number of significant digits but digits which are beyond the precision of the floating point representation will not be reflected in the mantissa of the number which is produced. e The exponent field which starts with and 'E' or 'e' is optional. e = The leading '+' sign in the exponent field may be omitted for positive exponents. e The resulting number should be in the range approximately 1e-99 to approximately 1e+99. 12-5 CHAPTER 13 LONG INTEGER MANAGEMENT e LongintCompare Compare two long integers AX: BX The left operand long integer. CX:DX The right operand long integer. RETURN: Flags < 0 If AX:BX < CX:DX Flags = 0 If AX:BX = CX:DX Flags >> 0 If AX:BX > CX:DX PANIC: None Compares two long integers for equality. The flags are set in the same way as for a normal compare for integers, i.e. CMP AX:BX, CX:DX. Note that the flags are set so that only the signed tests can be performed, i.e. JLE,JL,JE,JNE,JG,JGE and not the unsigned tests JB,JBE,JA,JAE. All registers are preserved by this service. e LongintMultiply Long integer multiplication AX:BX The left operand long integer. CX:DX The right operand long integer. RETURN: = Carry clear AX:BX Product. RETURN: Carry set OverflowErr AX:BX * CX:DX is bigger than 32 bits. PANIC: None Multiply two long integers together. If the resultant product overflows then an error will be returned by setting the carry flag. If no error occurs, the flags will not be set for the result; carry will be clear. e LongintDivide Long integer division AX: BX The left operand long integer (dividend). CX:DX The right operand long integer (divisor). RETURN: = Carry clear AX: BX The quotient. CX:DX The remainder. RETURN: Carry set DivideByZeroErr CX:DX is zero. PANIC: None 13-1 EPOC O/S SYSTEM SERVICES Divide one long integer by another. If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. If no error occurs, the flags will not be set for the result; carry will be clear. The remainder will have the same sign as the dividend. e LongUnsignedintCompare Compare 2 unsigned long integers AX:BX The left operand unsigned long integer. CX:DX The right operand unsigned long integer. RETURN: Flags << 0 If AX:BX < CX:DX Flags = 0 If AX:BX = CX:DX Flags > 0 If AX:BX > CX:DX PANIC: None Compares two unsigned long integers for equality. The flags are set in the same way as for a normal compare for integers, i.e. CMP AX:BX, CX:DX. Note that the flags are set so that only the unsigned tests can be performed, i.e. JBE,JB,JE,JNE,JA,JAE and not the signed tests JL,JLE,JG,JGE. All registers are preserved by this service. e LongUnsignedintMultiply Unsigned long integer multiplication AX:BX The left operand unsigned long integer. CX:DX The right operand unsigned long integer. RETURN: Carry clear AX:BX Product. RETURN: Carry set OverflowErr AX:BX * CX:DX is bigger than 32 bits. PANIC: None Multiply two unsigned long integers together. If the resultant product overflows, an error will be returned by setting the carry flag. If no error occurs, the flags will not be set for the result; carry will be clear. e LongUnsignedIntDivide Unsigned long integer division AX:BX The left operand unsigned long integer (dividend). CX:DX The right operand unsigned long integer (divisor). RETURN: Carry clear AX: BX The quotient. CX:DX The remainder. RETURN: Carry set DivideByZeroErr CX:DX is zero. PANIC: None Divide one unsigned long integer by another. If CX:DX (i.e. the divisor), is zero then an error will be returned and the carry flag will be set. If no error occurs, the flags will not be set for the result; carry will be clear. 13-2 13 LONG INTEGER MANAGEMENT LongUnsignedintRandom Unsigned long integer random number DS:BX Pointer to the unsigned long integer seed. RETURN: AX: BX The unsigned long integer random number. PANIC: None Return an unsigned long integer random number given the seed. The 4 bytes pointed to by BX are used to generate the next random number which is returned in AX:BX as well as being written back to the seed. The seed can start with any number required from which the same sequence of random numbers will be generated. CHAPTER 14 FLOATING POINT NUMBER HANDLING e FloatCompare Compare two Floats DI Pointer to left hand floating point operand. SI Pointer to right hand floating point operand. RETURN: Z flag set if [DIJ=[S]]. S flag set if [DI]<<[S]]. PANIC: None Compares the two floating point operands pointed to by SI and DI, setting the Z and the S flags as for [DI]-[SI]. The Z flag is set if the operands are equal and the S flag is set if [DI] is less than [SI]. ¢ FloatMultiply Multiply two floats DI Pointer to left hand (and destination) floating point operand. Si Pointer to right hand floating point operand. RETURN: = Carry clear [DI] RETURN: Carry set OverFlowError Product exponent overflowed. PANIC: None Multiplies the two floating point operands pointed to by SI and DI. Returns the product in [DI]. « FloatDivide Divide floats DI Pointer to left hand (and destination) floating point operand. SI Pointer to right hand floating point operand. RETURN: = Carry clear [DI] RETURN: Carry set OverFlowError Quotient exponent overflowed. PANIC: None Divides the operand at DI by the operand at SI and returns the quotient in [DI]. 14-1 EPOC O/S SYSTEM SERVICES e FloatAdd Add two Floats DI Pointer to left hand (and destination) floating point operand. SI Pointer to right hand floating point operand. RETURN: Carry clear [DI] RETURN: Carry set OverFlowError Sum exponent overflowed. PANIC: None Adds the two floating point operands pointed to by SI and DI. Returns the sum in [DI]. ¢ FloatSubtract Subtract Floats DI Pointer to left hand (and destination) floating point operand. SI Pointer to right hand floating point operand. RETURN: Carry clear [DI] RETURN: = Carry set OverFlowError Sum exponent overflowed. PANIC: None Subtracts the operand at SI from the operand at DI and returns the difference in [DI]. e FloatNegate Negate a Floats DI Pointer to floating point operand. RETURN: [DI] PANIC: None Negates the float at DI. ¢ FloatToLong Convert Float to a signed long SI Pointer to float operand to be converted. RETURN: Carry clear AX:BX Long integer result. RETURN: Carry set ArgumentErr Float not in range [-2**31,2**31-1]. PANIC: None Converts the floating point operand pointed to by SI to a 32 bit signed long integer in AX:BX with the most significant word in AX. ¢ FloatTtoUnsignedLong Convert Float to unsigned long SI Pointer to float operand to be converted. RETURN: Carry clear AX: BX Unsigned long integer result. RETURN: Carry set ArgumentErr Float not in range [-2*32+1,2**32-1]. PANIC: None Converts the floating point operand pointed to by SI to a 32 bit unsigned integer in AX:BX with the most significant word in AX. Note that the sign of the float is ignored. 14-2 14. FLOATING POINT NUMBER HANDLING ¢ FloatTolnt Convert Float to a signed integer SI Pointer to float operand to be converted. RETURN: Carry clear AX unsigned integer result. RETURN: Carry set ArgumentErr Float not in range [-32768,32767]. PANIC: None Converts the floating point operand pointed to by SI to a 16 bit signed integer in AX. ¢ FloatToUnsignedint Convert Float to unsigned integer SI Pointer to float operand to be converted. RETURN: Carry clear AX Integer result. RETURN: Carry set ArgumentErr Float not in range [-65535,65535] PANIC: None Converts the floating point operand pointed to by SI to a 16 bit unsigned integer in AX. The sign of the float is ignored. ¢ LongToFloat Convert signed long to Float AX:BX Signed long to be converted. DI Pointer to destination float. RETURN: [DI] PANIC: None Converts the signed 32 bit integer in AX:BX to a float at DI. ¢ IntToFloat Convert signed integer to Float AX Signed integer to be converted. DI Pointer to destination float. RETURN: [DI] PANIC: None Converts the signed 16 bit integer in AX to a float at DI. ¢ UnsignedIintToFloat Convert unsigned integer to Float AX Unsigned integer to be converted. DI Pointer to destination float. RETURN: [DI] PANIC: None Converts the unsigned 16 bit integer in AX to a float at DI. CHAPTER 15 FLOATING POINT FUNCTION INTERFACE FloatASin Arcsine of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float. PANIC: None Calculates the Arcsine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. FloatATan Arctangent of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: = Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float. PANIC: None Calculates the Arctangent in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. FloatCos Cosine of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: = Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float, or argument not in range. PANIC: None Calculates the Cosine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. 15-1 EPOC O/S SYSTEM SERVICES FloatExp Exponentiation of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float. PANIC: None Calculates the exponentiation of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. Floatint Zero fractional part of a Float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float. PANIC: None Removes the fractional part of the float in [SI] and returns the result as a float in [DI]. [SI] is preserved unless SI equals DI. FloatLn Natural logarithm of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float, or argument not greater than zero. PANIC: None Calculates the Natural Logarithm of a double argument in [SI] returning the result in [DI]. [ST] is preserved unless SI equals DI. FloatLog Logarithm of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float, or argument not greater than zero. PANIC: None Calculates the Logarithm of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless ST equals DI. 15 -2 15 FLOATING POINT FUNCTION INTERFACE FloatMod Modulo of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. Dx Pointer to floating point modulo value. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float. OverflowErr Integer overflow. PANIC: None Calculates [SI] modulo [DX] returning the result in [DI]. The calculation is [DI] = [ST] - FloatInt({[S1]/[DX])*[DX]. [SI] and [DX] is preserved unless SI or DX equals DI. FloatPow Power of two Floats DI Pointer to destination floating point operand. SI Pointer to floating point base. Dx Pointer to floating point power. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float, 040, or [SI]<<0O with [DI] not integral. OverflowErr Integer overflow. PANIC: None Calculates [SI] raised to the power of [DI] returning the result in [DI]. [SI] and [DX] are preserved unless SI or DI equals DI. FloatRand Float random number DI Pointer to destination floating point number. SI Pointer to unsigned long integer seed. RETURN: Carry clear [DI] RETURN: Carry Set None PANIC: None Generates a pseudo random number using the unsigned long integer seed in [SI] and returns the result in [DI]. [SI] is preserved unless SI equals DI. FloatSin Sine of a Float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float, or argument not in range. PANIC: None Calculates the Sine in radians of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. 15-3 EPOC O/S SYSTEM SERVICES FloatSqrt Square root of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set ArgumentErr Invalid float or argument less than 0. PANIC: None Calculates the square root of a double argument in [SI] returning the result in [DI]. [SI] is preserved unless SI equals DI. FloatTangent Tangent of a float DI Pointer to destination floating point operand. SI Pointer to floating point function argument. RETURN: Carry clear [DI] RETURN: Carry Set OverflowErr Input argument equals PI/2. PANIC: None Calculates the Tangent in radians of a double argument in [SI] returning the result in [DI]. [ST] is preserved unless SI equals DI. 15-4 CHAPTER 16 CHARACTER MANAGEMENT ¢ CharlsDigit Character is a digit AL The character to be tested. RETURN: Z flag = 0 If character is a digit. Z flag = 1 If character is not a digit. PANIC: None Returns the flags set depending on whether the character in AL is a digit. This is a language dependent service. e CharlsHexDigit Character is a hexadecimal digit AL The character to be tested. RETURN: Z flag = 0 If character is a hexadecimal digit. Z flag = 1 If character is not a hexadecimal digit. PANIC: None Returns the flags set depending on whether the character in AL is a hexadecimal digit. This is a language dependent service. ¢ CharlsPrintable Character is printable AL The character to be tested. RETURN: Z flag = 0 If character is printable. Z flag = 1 If character is not printable. PANIC: None Returns the flags set depending on whether the character in AL is printable. This is a language dependent service. ¢ CharlsAlphabetic Character is alphabetic AL The character to be tested. RETURN: Z flag = 0 If character is alphabetic. Z flag = 1 If character is not alphabetic. PANIC: None Returns the flags set depending on whether the character in AL is alphabetic. This is a language dependent service. 16-1 EPOC O/S SYSTEM SERVICES ¢ CharlsAlphaNumeric AL RETURN: Z flag = 0 Z flag = 1 PANIC: None Character is alphabetic or digit The character to be tested. If character is alphanumeric. If character is not alphanumeric. Returns the flags set depending on whether the character in AL is alphanumeric. This is a language dependent service. « CharlsUpperCase AL RETURN: Z flag = 0 Z flag =1 PANIC: None Character is upper case The character to be tested. If character is upper case. If character is not upper case. Returns the flags set depending on whether the character in AL is upper case. This is a language dependent service. e CharlsLowerCase AL RETURN: Z flag = 0 Z flag = 1 PANIC: None Character is lower case The character to be tested. If character is lower case. If character is not lower case. Returns the flags set depending on whether the character in AL is lower case. This is a language dependent service. « CharlsSpace AL RETURN: Z flag = 0 Z flag = 1 PANIC: None Character is space The character to be tested. If character is space. If character is not space. Returns the flags set depending on whether the character in AL is a space. This is a language dependent service. e CharlsPunctuation AL RETURN: Z flag = 0 Z flag = 1 PANIC: None Character is punctuation The character to be tested. If character is punctuation. If character is not punctuation. Returns the flags set depending on whether the character in AL is punctuation. This is a language dependent service. 16-2 e CharlsGraphic AL RETURN: Z flag = 0 Z flag = 1 PANIC: None 16 CHARACTER MANAGEMENT Character is graphic The character to be tested. If character is graphic. If character is not graphic. Returns the flags set depending on whether the character in AL is graphic. This is a language dependent service. e CharlsControl AL RETURN: Z flag = 0 Z flag = 1 PANIC: None Character is control The character to be tested. If character is control. If character is not control. Returns the flags set depending on whether the character in AL is control. This is a language dependent service. ¢ CharToUpperChar AL AH RETURN: AL AH PANIC: None Characters to upper case A character to be converted. A character to be converted. Converted to upper case. Converted to upper case. Converts the characters in AH and AL to upper case. This is a language dependent service. e CharToLowerChar AL AH RETURN: AL AH PANIC: None Characters to lower case A character to be converted. A character to be converted. Converted to lower case. Converted to lower case. Converts the characters in AH and AL to lower case. This is a language dependent service. e CharToFoldedChar AL AH RETURN: AL AH PANIC: None Characters to folded characters A character to be folded. A character to be folded. Folded. Folded. Folds the characters in AH and AL. This is a language dependent service. CHAPTER 17 BUFFER MANAGEMENT ¢ BufferCopy Copy one buffer to another DS:SI Pointer to source buffer. ES:DI Pointer to target buffer. CX Number of bytes to copy. RETURN: None PANIC: None Copies CX bytes of data from the source buffer to the target buffer. The service is optimised to perform the copy in words. If the target buffer pointer is greater than the source buffer pointer, the copy will be done backwards so as to avoid the possibility of corrupting the source buffer during the copy. In most cases it is better to use the REP MOVSW 80C86 instruction. ¢ BufferSwap Swap the contents of two buffers DS:SI Pointer to one of the buffers. ES:DI Pointer to the other buffer. CX The number of bytes to swap. RETURN: None PANIC: None Swap the contents of the two buffers pointed to by SI and DI. CX bytes of data will be swapped. This service is optimised to use words. ¢ BufferCompare Compare one buffer with another DS:SI Pointer to left operand buffer. ES:DI Pointer to right operand buffer. CX Number of bytes in the left operand. BX Number of bytes in the right operand. RETURN: Flags < 0 If [SY] < [DI] Flags = 0 If [SI] = [DI] Flags > 0 If [SY] > [DI] PANIC: None Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will lead to unpredictable results. This service makes the comparison dependent on the case. 17-1 EPOC O/S SYSTEM SERVICES « BufferCompareFolded Compare a buffer with another folded DS:SI Pointer to left operand buffer. ES:DI Pointer to right operand buffer. cx Number of bytes in the left operand. BX Number of bytes in the right operand. RETURN: Flags < 0 If [SI] < [DI] Flags = 0 If [SI] = [DI] Flags > 0 If [SI] > [DI] PANIC: None Compares two buffers for equality. The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI] but only sets the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will lead to unpredictable results. This service is case independent and is language dependent. « BufferLocate Locate a character in a buffer AH The character to be located. DS:SI Pointer to the buffer to be searched. cx The number of bytes in the buffer to be searched. RETURN: Carry clear AX Index of the character in the string. RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the character is located then the index into the buffer is returned in AX. The index of the first character in the buffer is 0. This service is case dependent. « BufferLocateFolded Locate a character in a buffer folded AH The character to be located. DS:SI Pointer to the buffer to be searched. CX The number of bytes in the buffer to be searched. RETURN: Carry clear AX Index of the character in the string. RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH in the buffer pointed to by SI. CX bytes of the buffer will searched. If the character is located then the index into the buffer is returned in AX. The index of the first character in the buffer is 0. This service is case independent. 17-2 e BufferSubBuffer DS:SI ES:DI cx BX RETURN: Carry clear AX RETURN: Carry set AL undefined PANIC: None 17 BUFFER MANAGEMENT Find a sub-buffer in a buffer Pointer to the buffer to be searched. Pointer to the buffer to be located. The number of bytes in buffer being searched. The number of bytes in sub-buffer. Offset of the sub-buffer within the buffer. Sub-buffer not found. Locates a buffer as a sub-buffer within another buffer. If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to by SI and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a sub-buffer, then the service returns the carry flag set. This service is case dependent. - BufferSubBufferFolded Find a sub-buffer in a buffer folded DS:SI Pointer to the buffer to be searched. ES:DI Pointer to the buffer to be located. cx The number of bytes in buffer being searched. BX The number of bytes in sub-buffer. RETURN: Carry clear AX Offset of the sub-buffer in the buffer. RETURN: Carry set AL undefined. PANIC: None Locates a buffer as a sub-buffer within another buffer. Sub-buffer not found. If the buffer pointed to by DI and of length BX is a sub-buffer of the buffer pointed to by SI and of length CX, then the service returns the index of the first occurrence of the sub-buffer within the buffer pointed to by SI, and with the carry flag clear. The index of the first character in the buffer is 0. If the buffer is not a sub-buffer, then the service returns the carry flag set. This service is case independent. - BufferMatch Match a wild card buffer DS:SI Pointer to the buffer to be searched. CX Length of the buffer to be searched. ES:DI Pointer to the wild card match buffer. Dx Length of the match buffer. RETURN: Carry clear Match RETURN: = Carry set AL undefined PANIC: None Search a buffer for a match with the supplied wild card buffer. No match. 17 -3 EPOC O/S SYSTEM SERVICES If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does not match then the service will return with carry set. The matchany character will match any set of characters. The MatchSingle character will match any single character. This service is case dependent. - BufferMatchFolded Match a wild card buffer folded DS:SI Pointer to the buffer to be searched. cx Length of the buffer to be searched. ES:DI Pointer to the wild card match buffer. Dx Length of the match buffer. RETURN: Carry clear Match RETURN: = Carry set AL undefined No match. PANIC: None Search a buffer for a match with the supplied wild card buffer. If the wild card buffer matches then the service will return with carry clear. If the wild card buffer does not match then the service will return with carry set. The Matchany character will match any set of characters. The MatchSingle character will match any single character. This service is case independent. - BufferJustify Justify a buffer DS:SI Pointer to the buffer to be justified. Cx Length of the buffer to be justified. ES:DI Pointer to the target buffer. BX Length of the target buffer. DL JustifyLeft OF JustifyCentre Of JustifyRight. DH The fill character. RETURN: AX Points to the character after the last byte copied to the target buffer. PANIC: None Justifies a source buffer DS:SI of length CX into a target buffer ES:DI of length BX using the justification method passed in DL and the fill character passed in DH. If BX is negative, then BX bytes are just copied to the target buffer. If DL is not one of the 3 options then the left justified method will be used by default. 17-4 CHAPTER 18 STRING MANAGEMENT ¢ StringCopy Copy one string to another DS:SI Pointer to source string. ES:DI Pointer to target string. RETURN: None PANIC: None Copies the source string to the target string. ¢ StringCopyFolded Copy one string to another folded DS:SI Pointer to source string. ES:DI Pointer to target string. RETURN: None PANIC: None Copies the source string to the target string. Characters are folded as they are copied. ¢ StringConvertToFolded Convert a string to folded DS:SI Pointer to string to be folded. RETURN: None PANIC: None Converts the string pointed to by SI to folded. ¢ StringCapitalise Capitalise a string DS:SI Pointer to string to be capitalised. RETURN: None PANIC: None Converts the string pointed to by SI so that the first letter is uppercase and the remaining characters are lowercase. e StringCompare Compare one string with another DS:SI Pointer to left operand string. ES:DI Pointer to right operand string. RETURN: Flags < 0 If [SY] < [DI] Flags = 0 If [SI] = [DI] Flags > 0 If [ST] > [DI] PANIC: None Compares two strings for equality. 18-1 EPOC O/S SYSTEM SERVICES The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will lead to unpredictable results. This service is case dependent. ¢ StringCompareFolded Compare a string with another folded DS:SI Pointer to left operand string. ES:DI Pointer to right operand string. RETURN: Flags < 0 If [SI] < [DI] Flags = 0 If [ST] = [DI] Flags > 0 If [ST] > [DI] PANIC: None Compares two strings for equality. The flags are set in the same way as for a normal compare for integers, i.e. CMP [DI], [SI], but only sets the flags such that the unsigned comparisons can be used. The signed comparisons such as JAE etc. will lead to unpredictable results. This service is case independent and language dependent. ¢ StringMatch Match a wild card string DS:SI Pointer to the string to be searched. ES:DI Pointer to the wild card match string. RETURN: Carry clear Match RETURN: = Carry set AL undefined No match. PANIC: None Search a string for a match with the supplied wild card string. If the wild card string matches then the service will return with carry clear. If the wild card string does not match then the service will return with carry set. The mat chany character will match any set of characters. The matchSingle character will match any single character. This service is case dependent. ¢ StringMatchFolded Match a wild card string folded DS:SI Pointer to the string to be searched. ES:DI Pointer to the wild card match string. RETURN: Carry clear Match RETURN: = Carry set AL undefined. No match. PANIC: None Search a string for a match with the supplied wild card string. If the wild card string matches then the service will return with carry clear. If the wild card string does not match then the service will return with carry set. The mat chany character will match any set of characters. The matchsingle character will match any single character. This service is case independent. 18 -2 18 STRING MANAGEMENT « StringLocate Locate a character in a string AH The character to be located. DS:SI Pointer to the string to be searched. RETURN: Carry clear AX Index of the character in the string. RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH within the string pointed to by SI. If the character is located then the index into the string is returned in AX. The index of the first character in the string is 0. This service is case dependent. ¢ StringLocateFolded Locate a character in a string folded AH The character to be located. DS:SI Pointer to the string to be searched. RETURN: Carry clear AX Index of the character in the string. RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH within the string pointed to by SI. If the character is located then the index into the string is returned in AX. The index of the first character in the string is 0. This service is case independent. ¢ StringLocatelnReverse Locate a character in reverse AH The character to be located. DS:SI Pointer to the string to be searched. RETURN: Carry clear AX Index of the character in the string. RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH within the string pointed to by SI in reverse order. If the character is located then the index into the string is returned in AX. The index of the first character in the string is 0. This service is case dependent. ¢ StringLocatelnReverseFolded Locate char’ in reverse folded AH The character to be located. DS:SI Pointer to the string to be searched. RETURN: Carry clear AX Index of the character in the string. EPOC O/S SYSTEM SERVICES RETURN: Carry set AL undefined Character is not in the string. PANIC: None Locates the character in AH within the string pointed to by SI in reverse order. If the character is located then the index into the string is returned in AX. The index of the first character in the string is 0. This service is case independent. ¢ StringSubString Find a substring in a string DS:SI Pointer to the string to be searched. ES:DI Pointer to the string to be located. RETURN: Carry clear AX Offset of the substring in the string. RETURN: Carry set AL undefined Substring not found. PANIC: None Locates a string as a substring within another string. If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string is 0. If the string is not a substring, then the service returns with the carry flag set. This service is case dependent. ¢ StringSubStringFolded Find a substring in a string folded DS:SI Pointer to the string to be searched. ES:DI Pointer to the string to be located. RETURN: Carry clear AX Offset of the substring in the string. RETURN: Carry set AL undefined Substring not found. PANIC: None Locates a string as a substring within another string. If the string pointed to by DI is a substring of the string pointed to by SI, then the service returns the index of the first occurrence of the substring; the carry flag is clear. The index of the first character in the string is 0. If the string is not a substring, then the service returns with the carry flag set. This service is case independent and language dependent. ¢ StringLength Length of a string ES:DI Pointer to the string whose length is to be found. RETURN: AX The length of string. PANIC: None Returns the length of the string pointed to by DI excluding the terminating zero. 18-4 18 STRING MANAGEMENT ¢ StringValidateName Validate a system name AL Maximum number of characters in the name allowed in the name. AH Non 0 - An extension is valid. 0 - An extension is invalid. ES:DI Pointer to the string to be validated. RETURN: Carry clear String is valid. RETURN: = Carry set NameErr String is not valid. PANIC: None Validates that the string at DI points to a valid system name. An extension is only allowed if AH is non zero. AL specifies the number of characters that can be in the name before the period. The BNF for a valid name is as follows: ANY := ALPHA | DIGIT | $ | _ NAME := ALPHA [ [ANY]*7 [. [ANY]*3 ]] 18-5 CHAPTER 19 GENERAL MANAGEMENT Version numbers A version number is a 16 bit integer. If the 16 bit integer is converted to 4 hex digits, i.e. XY YZ, then the version is: X.YYZ where X is the major release number, YY is the minor release number and Z is the version type. The version type may have three values. e A- Alpha release. e 6B - Beta release. e F - Final release. Thus a typical version number 0x100f would be 1.00F. GenVersion Get the operating system version number None RETURN: AX The operating system version number. PANIC: None Returns the operating system version number as a 16 bit integer. GenRomVersion Get the ROM version number None RETURN: AX The ROM version number. PANIC: None Returns the ROM version number. The operating system is never released on its own and is always supplied with a number of files in its built in ROM disk. The tool which builds the operating system together with the ROM disk allows a version number to be specified. This service can be used to retrieve the version number so specified. 19-1 EPOC O/S SYSTEM SERVICES GenLcdType Get the system LCD type None RETURN: AL The LCD type. PANIC: None Returns the system LCD type. The various types are defined in epocdefs.inc. GenStartReason Get the system cold start reason None RETURN: AL The cold start reason. PANIC: None Returns the system cold start reason. The operating system can perform a cold start for five reasons: e Initialise; system RAM is invalid. e Power fail; the system was forced to power down, but RAM is still valid. e Reset; the user requested a reset, but RAM is still valid. e =Kernel fault; a serious fault occurred while executing in the operating system kernel. e New OSS restart; a new operating system has been programmed into the flash memory and a restart has occurred. The shell on first starting up should request the cold start reason and if it is not an initialise it should inform the user of the reason for the cold start. « GenDataSegment Get the operating system data segment None RETURN: ES The operating system data segment. PANIC: None Returns the operating system's data segment address. This service is reserved for use by system utilities. GenGetCountryData Get the country data BX Pointer to a cDataEnt structure. RETURN: None PANIC: None Returns the country dependent data currently installed. The operating system on start-up copies the country dependent data from the configuration file into RAM so that the GensetcountryData can be called to update the information. GenSetCountryData Set the country data ES:BX Pointer to a cDataEnt structure. RETURN: None PANIC: None Sets the country dependent data. The source of the data is the cbat arnt structure pointed to by ES:BX. 19-2 19 GENERAL MANAGEMENT GenGetOsData Get the O/S data DI Pointer to a buffer to receive the data. SI Offset in the operating system data space. cx The number of bytes to be copied. RETURN: None PANIC: None Copies data from the operating system's data space to the buffer provided. All operating system handles are the actual address in the operating system data space of the appropriate control entry. For example, the handle returned by the Filzxecute service is the address in the operating system data space of the z_proc process control entry. By fetching this data, a program can determine many things about the state of a process. GenGetErrorText Get error text AL The error number. BX Pointer to a buffer to receive the error text. RETURN: None PANIC: None Returns the text associated with an error number. The buffer pointed to by BX must be MaxErrorTextsize in length. If AL is not negative or it contains an error unknown to the operating system, then "Unknown error [-xx]" will be returned where xx is the unknown error number. This is a language dependent service. e Dummy Dummy service None RETURN: None PANIC: None This service provides a means for generating a call to a known location in the operating system. It is used mainly for debugging the operating system. The service itself does nothing at all. GenParse Generic file name parser BX Pointer to a GenParseEnt Structure. RETURN: Carry clear Success RETURN: = Carry set NameErr Invalid name. PANIC: None This service provides a generic parse service which can be used to parse file names. This service should not be confused with the rilparse service. FilParse Calls the file server which in turn calls a file system to parse the file name and this will always be successful, assuming that the file name obeys the naming rules for the target file system. This service can only parse generic MSDOS like file names. The generic parser considers a file name to consist of up to five components: SystemName Drive Path Name Extension A SystemName consists of a FileSystemName followed by two ':'s. A Drive consists of a DriveName followed by DriveSeparator. EPOC O/S SYSTEM SERVICES A Path consists of a PathSeparator followed by zero or more DirectoryName PathSeparator pairs. An Extension consists of an ExtensionSeparator followed by an ExtensionName. The GenParseEnt structure allows a single character to be specified for each of the separators and the maximum size for each of the four components. Note that the maximum size of a component includes any separators. Note also that the SystemName separator of two ':'s cannot be specified. For MSDOS filing systems, the values which should be loaded into the structure are as follows: GenParseDeviceSeparator= ':' GenParsePathSeparator= '\' GenParseExtSeparator = GenParseMaxDeviceSize= 2 GenParseMaxPathSize = 64 GenParseMaxNameSize = 8 vot GenParseMaxExtSize = 4 The remaining fields of the structure specify pointers to three input names, a pointer to the output buffer and a pointer to a FullParseEnt Structure. Parsing is effected as follows. The three input strings are prioritised in the order GenParseSourceNamePtr,GenParseRelatedNamePtr and GenParseDefaultsPtr. Each of these input strings is parsed into its four components (some of which may be missing). The resulting string is built by taking components from the first string. Any missing components are filled in from the second string (where they exist). Any components still missing are filled in from the third string. Thus, if the "source" string does not have a drive, but the "related" string does, then the resulting name will use the drive as specified in the "related" string. When the resulting string has been built, the size of each component is put into the FullParseEnt structure. Finally, the name and extension components are examined for the wild card characters '?' and '*' and, if found, the parseWildName and ParseWildext flags are set appropriately in the FullParseEnt .FullParseFlags field. If either parsewildName Of ParseWildExt is set then ParseWildAny is also set. GenDeferredMode Set deferred mode AL 0 - Increment deferred mode. Non 0 - Decrement deferred mode RETURN: None PANIC: None This service only applies to the MC version of the operating system and can be used to defer some of the work which is performed in the 32Hz. tick interrupt. Calling the service with AL equal to zero will defer keyboard and mouse polling, parallel I/O polling and the piezo sound system. This has the additional benefit of stopping the serial channel from being temporarily diverted by the tick interrupt service routines. Normal operation can be resumed by calling this service with AL set to a non zero value. If the tick interrupt overhead must be reduced further then the anti-nesting flag can be incremented. This is a byte at address 0438h in the operating system data space. While this flag is set, only the time is kept up to date but be warned, pre-emptive multi tasking is disabled as are all timer services. GenNotify Notify by text BX Pointer to the first message. cx Pointer to the second message or zero. Dx Pointer to the first option or zero. DI Pointer to the second option or zero. SI Pointer to the third option or zero. 19-4 19 GENERAL MANAGEMENT RETURN: Carry clear AL 0 - First option chosen by the user. 1 - Second option chosen by the user 2 - Third option chosen by the user. RETURN: Carry set FailErr No notify process running. PANIC: None This service will send a message to the notification process and await the result from the notifier, returning the result in AL. If a notifier is not currently running then railerr will be returned. BX and CX specify two zero terminated text messages which will be displayed by the notifier process. Each string can be up to MaxNot ifyTextSize in length including the zero terminator. CX can be optionally zero, in which case the second message line will be blank. DX, DI and SI specify up to three options which the user may select. The selected option is returned in AL and will be 0 if the DX option is chosen, 1| if the DI option is chosen and 2 if the SI option is chosen. By convention, if all the options are specified as 0 then this is the same as having DX point to an option of "CONTINUE". Each option string can be up to MaxOptionTextSize in length including the zero terminator. Finally if DI is 0 then SI should also be 0. The presentation of the notifier depends on the process which has hooked the notify interface. GenNotifyError Notify by error number AL The error number to be notified. BX Pointer to the first message. Dx Pointer to the first option or zero. DI Pointer to the second option or zero. SI Pointer to the third option or zero. RETURN: Carry clear AL 0 - First option chosen by the user. 1 - Second option chosen by the user. 2 - Third option chosen by the user. RETURN: Carry set FailErr No notify process running. PANIC: None This service first calls GenGetErrorText using AL as the parameter and then calls the GenNot ify service with CX pointing to the resultant error text, all other registers being the same. Only error numbers catered for by the configuration file should be notified using this service. It is reasonable to expect that all errors returned by the operating system can be notified with this service. GenNotifyHook Hook the notify interface BX The message number. RETURN: Carry clear Success RETURN: = Carry set FailErr Notify interface already hooked. PANIC: None This service allows a process to get a message in response to calls by all other processes to the GenNotify and GenNotifyError Services. The message will be delivered with the message number specified in BX and the message buffer will contain 5 words. The 5 words will consist of the 5 parameters to the GenNotify service in the order BX, CX, DX, DI and SI. Note that as 5 words need to be delivered, a process which hooks the notify interface should initialise messaging using the MessInit service with a size of at least 10 in BL. 19-5 EPOC O/S SYSTEM SERVICES The text string pointed to by the 5 parameters can be fetched from the requesting process using the ProcCopyFromBylId service. The result should be returned in CX when the MessFree service is called to give the result of the notification. A process which has hooked the notify interface should not call either the Gennot ify or the GenNotifyError services as it would then try and send itself a message, resulting in a lock up situation. It is probably wise for the process to disable file server notifies for itself by calling the GensetNotifystate to off, as it might be waiting for a file request to complete when the file server sends a notify message, resulting in lock up. If the process which has hooked the notify interface either exits or is panicked, then the supervisor will automatically free the interface so that another process can hook it. GenNotifyUnHook Unhook the notify interface None RETURN: None PANIC: PanicGenl Process does not have the interface hooked. This service will release the notify interface provided the process calling this service already has the interface hooked. If not, then the process will be panicked. GenGetRamSizelnParas Get addressable system RAM size None RETURN: AX Size of system ram in paragraphs. PANIC: None Returns the size, in paragraphs, of the currently addressable system RAM. On machines containing more than 512 kilobytes of RAM, this is not the same as the total amount of RAM that is fitted in the machine. GenGetCommandLine Get the command line None RETURN: AX Pointer to the command line or 0. PANIC: None Returns a pointer to the command line. The command line is a memory cell in the heap and can be freed if required with HeaprreeCell. Processes can also be started with no command line in which case this service will return 0. The address of the command line is also stored in the global variable ps: [Dat acommandPtr]. If the command line is freed then, for consistency, this global variable should be set to 0. The structure of the command line is a zero terminated string which contains the full path name used to start the process. This can be used to find other files associated with the process being run or to open the image file in order to access either added files or added DYLs. After the 0 of the zero terminated string is a leading byte string containing any arguments for the process. The string is leading byte counted so that binary arguments can be passed to programs. If the rFilExecute service 1s called with CX equal to 0 then no command line is passed. This should only be used to execute programs with no heap, since they obviously have nowhere to store the command line. It is preferable to have CX pointing to a string containing just the zero terminator. 19 -6 19 GENERAL MANAGEMENT GenGetSoundFlags Get the sound flags None RETURN: AX The sound flags. PANIC: None This service returns the current setting in the sound flags. The bits in the sound flags are as follows: @® SoundKeyboardEnable - If set, will enable keyboard clicks. ® SoundBuzzerEnable - If set, will enable the piezo sound system. @® SoundDeviceEnable - If set, will enable the SND: device driver. @ SoundLoud - If set, will make the piezo sound louder. ® SoundDisable - If set, will disable all sound in the system. GenSetSoundFlags Set the sound flags BX The new sound flags. RETURN: None PANIC: None This service sets the sound flags to the value in BX. The bits in the sound flags are as follows: ® SoundKeyboardEnable - If set, will enable keyboard clicks. @ SoundBuzzerEnable - If set, will enable the piezo sound system. @ SoundDeviceEnable - If set, will enable the SND: device driver. @ SoundLoud - If set, will make the piezo sound louder. ® SoundDisable - If set, will disable all sound in the system. GenSound Make sound with the piezo BX The duration of the sound in ticks. cx The pitch of the sound. RETURN: None PANIC: None This service will make a sound through the piezo for the duration specified in BX ticks and at the pitch specified in CX. The pitch can be calculated as (512/CX) KHz. The piezo uses very little power and is an easy way of generating sound, although it is quite soft. If greater sound complexity, or a louder sound is required then the SND: device driver can be used. Access to this service is controlled by a semaphore which has been pre-counted with 1. When service is requested, the semaphore is waited on and when completed the sound request is run. The service then returns to the process requesting the service. When the duration elapses, the semaphore is signalled, allowing the next service request to be processed. The effect of the above, assuming the piezo is not already in use, is that the first call to this service will complete immediately allowing the application to go about its business, but subsequent calls will wait until the current request is completed. If multiple processes make requests on this service, they are run on a first come first served basis. GenMarkActive Mark a process as active None RETURN: None PANIC: None This service informs the operating system that the process invoking this service is to be considered active. The operating system has the ability to auto switch off if no activity takes place within a certain length of time. Activity is considered to be a context switch to a process which has been marked active, 1.e. whenever the process executes, the timer controlling the auto switch off will be reset. 19-7 EPOC O/S SYSTEM SERVICES By default, all processes, when first created, are marked as active so that this service does not need to be called unless the GenMarkNonAct ive service has been called. GenMarkNonActive Mark a process as non-active None RETURN: None PANIC: None This service will inform the operating system that the process invoking this service is not to be considered active. The operating system has the ability to auto switch off if no activity takes place within a certain length of time. Activity is considered to be a context switch to a process which has been marked active. Hence marking a process as non-active will ensure that whenever the process executes, the timer controlling the auto switch off will not be reset. By default all processes, when first created, are marked as active so that this service must be called if the process is not to be considered as active. All servers must mark themselves as non-active, since they only execute when required by clients and the status of the client will determine activity or not. Thus if a client of the file server is non-active and requests some file activity, it will not be considered as activity because the file server is also marked as non-active. However if the client is active then by virtue of making the request to the file server, the auto switch off timer will be reset. If, for example, a program was left running displaying the time every second, by default, the machine would never switch off as every second the process would execute resetting the auto switch off timer, possibly not a desirable state of affairs. By marking the process as non-active then the activity of the process would not reset the timer and the machine would be able to switch off. GenGetText Get operating system text AL The number of the text message to be retrieved. ES:BX Pointer to the buffer to receive the text. RETURN: Carry clear Success RETURN: Carry set AL undefined Failed to find the message. PANIC: None This service will scan the operating system's built in configuration file for the text message associated with the number in AL. This service is similar to GenGetErrorText when AL is negative but can also be passed positive numbers. The text messages available depend entirely on the configuration file built into the ROM with the operating system. GenGetNotifyState Get notify state None RETURN: AL The notify state. PANIC: None This service will get the current notify state for the process. The file server, when it detects a problem which the user could possibly correct, will call the notifier process to inform the user of the error and any action which must be performed (e.g. replacing an SSD which had been accidentally removed before all files open on it were closed). If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is 1 then the notifier will be called. Some applications are intended to work in an unattended fashion so that a request for user attention would be to no avail. In this case, the state should be set to 0 so that the process itself can take any action required. By default, processes have the state set to 1. 19-8 19 GENERAL MANAGEMENT GenSetNotifyState Set notify state AL The notify state. RETURN: None PANIC: None This service will set the current notify state for the process. The file server, when it detects a problem which the user could possibly correct, will call the notifier process to inform the user of the error and any action which must be performed (e.g. replacing an SSD which had been accidentally removed before all files open on it were closed). If the state is 0 then the file server will not call the notifier and will return the error directly. If the state is 1 then the notifier will be called. Some applications are intended to work in an unattended fashion so that a request for user attention would be to no avail. In this case, the state should be set to 0 so that the process itself can take any action required. By default, processes have the state set to 1. GenGetAutoSwitchOffValue Get the auto switch off time RETURN: AX The auto switch off time in seconds. PANIC: None This service can be used to get the current auto switch off time. The time, in seconds, is returned in AX. It represents the amount of time which must expire with no activity before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By default, the auto switch off is set to 300 seconds. GenSetAutoSwitchOffValue Set the auto switch off time BX The auto switch off time in seconds. RETURN: None PANIC: None This service can be used to set the auto switch off time. The time, in seconds, is passed in BX. It represents the amount of time which must expire with no activity before the machine will auto switch off. If the value is -1 then auto switch off is disabled. By default, the auto switch off is set to 300 seconds. GenSetRevector Capture an interrupt AL The vector number. CX:BX The segment and offset on the interrupt routine. RETURN: None PANIC: None The operating system hooks all interrupt vectors to itself and in the case of hardware interrupt vectors and the special interrupt vectors, provides a shell interrupt service routine which will do all the right things to satisfy the operating system rules. This service allows a new interrupt service to be installed and should only be called by device drivers. As the new interrupt service is being called by the operating service through a shell the following rules apply to the interrupt service routine. e All registers may be destroyed except BP,SP and SS. e The routine should return with a far ret and not an iret. e If a re-schedule is required, then it should return with carry set; if not then carry should be clear. 19-9 EPOC O/S SYSTEM SERVICES The interrupts which may be re-vectored in this way are specified by constants in epocdefs.inc and are as follows: @ HwIntORevector - Divide by zero interrupt. @ HwInt1Revector - Single step interrupt. @ HwInt2Revector - Nmi interrupt. @ HwInt3Revector - Breakpoint interrupt. @ HwInt4Revector - Bounds check interrupt. e HwIrq0Revector - HwIrq7Revector - The 8 hardware interrupts. Note that under no circumstances should the Nmi or Irq0 (the tick interrupt) interrupts be re-vectored. GenResetRevector Release an interrupt AL The vector number. RETURN: None PANIC: None If the GensetRevector service has been used by a device driver to capture an interrupt, the interrupt should be released using this service when no longer required. This allows the operating system to point the vector to an appropriate default routine. The value in AL should be the re-vector number which was originally passed to GenSetRevector. GenGetLanguageCode Get the language code None RETURN: AX The language code. PANIC: None This service will return the language code for the configuration data built into the ROM with the operating system. Epoc is a configurable operating system and needs to be built with a configuration file using the OSROM.EXE utility. Configuration files are language dependent and, as such, a language code is included. The language code can be usefully used by applications which are multi-lingual to determine which language to present. The language codes are as follows: = Test = English = French = German = Spanish = Italian = Swedish = Danish = Norwegian oMWAtInauw fF WNEFE OO = Finnish = American = Swiss French = Swiss German = Portuguese Turkish Icelandic = Russian = Hungarian = Dutch 9 = Belgian Flemish AIHA BWNHEO ll 20 = Australian 21 = New Zealand 22 = Austrian 23 = Belgian French 19 - 10 19 GENERAL MANAGEMENT GenGetSuffixes Get suffix text ES:BX Pointer to buffer to receive the suffix text. RETURN: None PANIC: None This service will copy the language dependent suffixes from the configuration file into the buffer pointed to by ES:BX. The suffixes are fixed length zero terminated strings with a maximum length of three bytes including the zero terminator. Suffixes follow numbers for the day of the month (for example, the st in Ist. September 1990). Hence there are 31 suffixes so that ES:BX must point to a buffer of at least 31*3 bytes. This is a language dependent service. GenGetAmPmText Get the AM and PM text AL Zero - Get AM text Non zero - Get PM text. ES:BX Pointer to buffer to receive the AM and PM text. RETURN: None PANIC: None This service will copy the language dependent "AM" and "PM" text from the configuration file into the buffer pointed to by ES:BX. The two text strings are fixed length zero terminated strings with a maximum length of three bytes including the zero terminator. The "am" text is first, followed by the "pm" text. There are 2 strings of 3 bytes each so that ES:BX must point to a buffer of at least 6 bytes. This is a language dependent service. GenGetBatteryType Get the battery type None RETURN: AL The battery type. PANIC: None This service gets the current battery type. By default, Epoc sets the battery type to BatteryUnknown. The battery types are declared in the header file epocdefs.inc. On machines whose hardware does not support the detection of the battery type, a meaningful result depends on a prior call having been made to GenSetBatteryType. GenSetBatteryType Set the battery type AL The battery type. RETURN: None PANIC: None This service sets the current battery type. By default, Epoc sets the battery type to BatteryUnknown. The battery types are declared in the header file epocdefs.inc. Epoc needs to know about the various battery types because the levels at which low battery warning messages are issued depends on the type. If the battery type is BatteryUnknown then Epoc gives the same warning levels as for BatteryAlkaline. A call to this function is not required on machines, such as the Workabout, whose hardware supports detection of the battery type. 19-11 EPOC O/S SYSTEM SERVICES GenCrc Generate a CRC cx The number of bytes in the buffer. DX The current CRC. DS:SI Pointer to the buffer to be CRC checked. RETURN: AX The updated CRC check. PANIC: None This service will generate a CRC polynomial checksum (X power 16 + X power 12 + X power 5 + 1, as recommended by CCITT) from the buffer pointed to by DS:SI containing CX bytes. If the checksum is being started then the value in DX should be passed as 0. ¢ GenintByNumber Interrupt by number AL The interrupt number. DS:SI Pointer to the input register values. DS:DI Pointer to the output register values. RETURN: AX The flags register after the call. PANIC: Depends on the interrupt called. This service can be used to call any software interrupt and is provided to make calling the operating system easier from high level languages. The register values are stored sequentially as 6 words and represent the values for AX, BX, CX, DX, SI and DI. BP is never needed by the operating system and so is not required. DS:SI and DS:DI can point to the same memory location. The value returned is the flags register because although the carry flag is the most important, some of the operating system routines also set the arithmetic flags. The carry flag is in bit O of the returned result in AX. GenEnvBufferGet Get environment variable ES:DI Pointer to the environment variable name. DL Length of environment variable name. ES:SI Pointer to the buffer to receive the variable's value. RETURN: Carry clear AX The length of the data returned in ES:SI. RETURN: Carry set NotExistsErr No environment variable of the specified name exists. PANIC: None This service will locate an environment variable. The name of the variable is pointed to by ES:DI and has a length of DL bytes. The name may include wild cards, in which case the first matching name will be found. The value of the environment variable is copied to ES:SI and the length of this data is returned in AX. The maximum size of an environment variable's data is 255 bytes. GenEnvBufferSet Set environment variable ES:DI Pointer to the environment variable name. DL Length of environment variable name. ES:SI Pointer to the buffer containing the variable's data. CL The length of the data as ES:SI. 19 - 12 19 GENERAL MANAGEMENT RETURN: = Carry clear Success RETURN: = Carry set NoMemoryErr No space available to store environment variable. FailErr Environment variable name contained wild cards. PANIC: PanicEnv0 DL exceeded MaxEnvNameSize This service will either add or replace an environment variable. The name of the variable is pointed to by ES:DI and has a length of DL bytes. The name may not include wild cards nor exceed MaxEnvNameSize. The value of the environment variable is pointed to by ES:SI and the length of the data to be copied is in CL. Since the data is a buffer of length CL there is no restriction on what data may be placed in the buffer. The maximum size of an environment variable's data is 255 bytes. GenEnvBufferDelete Delete environment variable ES:DI Pointer to the environment variable name. DL Length of environment variable name. RETURN: Carry clear Success RETURN: = Carry set NotExistsErr No environment variable of the specified name exists. PANIC: None This service will delete an environment variable. The name of the variable is pointed to by ES:DI and has a length of DL bytes. The name may include wild cards in which case the first matching name is deleted. GenEnvBufferFind Find environment variable BX The find handle. ES:DI Pointer to the environment variable name. DL Length of environment variable name. ES:SI Pointer to the buffer to receive the variable's data. RETURN: Carry clear AX The next find handle. RETURN: Carry set EofErr No more matching environment variables. PANIC: None This service will find all occurrences of environment variables which match the supplied wild card name. The wild card name is pointed to by ES:DI and has a length of DL. A wild card of "*" will locate all environment variables. When this routine is first called, BX must contain zero; on subsequent calls, it must contain the value returned in AX. The wild card match string must remain the same on successive calls. zofErr is returned when there are no more matching names. After a successful call, the buffer pointed to by ES:SI contains two leading byte strings. The first string contains the name of the environment variable while the second string contains its value. The maximum size of an environment variable's data is 255 bytes. 19 - 13 EPOC O/S SYSTEM SERVICES GenEnvStringGet Get string environment variable ES:DI Pointer to the environment variable name string. ES:SI Pointer to the buffer to receive the variable's value. RETURN: Carry clear Success RETURN: = Carry set NotExistsErr No environment variable of the specified name exists. PANIC: None This service will locate an environment variable. The name of the variable is pointed to by ES:DI. The name may include wild cards, in which case the first matching name will be found. The value of the environment variable will be copied to ES:SI and will be zero terminated. Environment variables should not include the byte 0 as this would terminate the string prematurely. The maximum length of the string is 256 bytes including the terminating zero. GenEnvStringSet Set string environment variable ES:DI Pointer to the environment variable name. ES:SI Pointer to the string containing the variable's data. RETURN: Carry clear Success RETURN: = Carry set NoMemoryErr No space available to store environment variable. FailErr Environment variable name contained wild cards. PANIC: PanicEnv0 The name string exceeded MaxEnvNameSize This service will either add or replace an environment variable. The name of the variable is pointed to by ES:DI. The name may not include wild cards nor exceed MaxEnvNameSize. The value of the environment variable is pointed to by the string at ES:SI. The maximum size of the string should be limited to 255 bytes not including the zero terminator. Should the string be longer it will truncated module 256. GenEnvStringDelete Delete string environment variable ES:DI Pointer to the environment variable name. RETURN: Carry clear Success RETURN: = Carry set NotExistsErr No environment variable of the specified name exists. PANIC: None This service will delete an environment variable. The name of the variable is pointed to by ES:DI. The name may include wild cards in which case the first matching name is deleted. GenEnvStringFind Find string environment variable BX The find handle. ES:DI Pointer to the environment variable name. ES:SI Pointer to the buffer to receive the variable's name. ES:CX Pointer to the buffer to receive the variable's data. RETURN: Carry clear AX The next find handle. 19-14 19 GENERAL MANAGEMENT RETURN: Carry set EofErr No more matching environment variables. PANIC: None This service will find all occurrences of environment variables which match the supplied wild card name. The wild card name is pointed to by ES:DI. A wild card of "*" will locate all the environment variables. When this routine is first called, BX must contain zero; on subsequent calls it must contain the value returned in AX. The wild card match string must remain the same on successive calls. EofErr is returned when there are no more matching names. After a successful call, the buffer pointed to by ES:SI contains the name of the environment variable which was found, as a zero terminated string. The maximum size of the name of an environment variable iS MaxEnvNameSize. The buffer pointed to by ES:CX contains the value of the environment variable which was found, as a zero terminated string. The maximum size of the data is 256 bytes, including the zero terminator. GenAlarmHook Hook the alarm interface BX The message number. RETURN: Carry clear Success RETURN: Carry set FailErr Alarm interface already hooked. PANIC: None This service allows a process to capture the alarm interface built into the operating system. Having hooked the alarm interface the ALM: device driver can be used to request alarms from the alarm server. The availability of an alarm server and what it does, varies from machine to machine and the appropriate documentation for the specific machine should be consulted. GenAlarmUnHook Unhook the alarm interface None RETURN: None PANIC: PanicGenl Process does not have the interface hooked. This service will release the Alarm interface if the process calling this service already has the interface hooked. If it does not, the process will be panicked. GenAlarmld Get the pid of the alarm server None RETURN: AX The alarm server pid. PANIC: None This service will return the ID of the alarm server. If the alarm interface is not currently hooked then this service will return zero in AX. GenTickle Reset the auto switch off timer None RETURN: None PANIC: None This service will reset the auto switch off timer to the value as specified to the last GenSet Aut oSwitchOffValue. This routine is useful for processes which have called GenMarkNonAct ive and require to "tickle" the auto switch off from time to time. 19 - 15 EPOC O/S SYSTEM SERVICES GenSetOnEvents Control on events AL The find handle. RETURN: None PANIC: None This service controls whether the system will report on-events(for example, reporting to the window server when the machine switches on). If AL is non-zero then on-events will be reported. If AL is zero, they will not. By default on-events are reported on Series 3 and Series 3a operating systems and not reported on other versions. ©GenGetAutoMains Get state for auto-sw-off if mains present RETURN: AX The current auto-switch-off state for when mains is present. PANIC: None Returns a non-zero value in AX if auto-switch-off is disabled when mains is present, and zero if enabled. ©GenSetAutoMains Disable/enable auto-sw-off if mains present AL Flag specifying whether to enable or disable. RETURN: None PANIC: None Enable or disable auto-switch-off if mains is present. If AL is non-zero, auto-switch-off is disabled, otherwise it is enabled. By default auto-switch-off is enabled. Even if enabled, the machine will not switch off when mains is absent if auto-switch-off has been stopped by calling GensetAutoSwitchOffValue with value -1. 19 - 16 CHAPTER 20 DATABASE FILE MANAGEMENT File structure Database files (DBFs) start with a 22 byte header which contains the following information: Offset in header Information 0 - 15 Zero terminated file signature. 16, 17 Version of DBF software used to produce the file. 18, 19 Offset from the start of the file to the first record. 20, 21 Minimum version of DBF software required. Note that all 16 bytes of the file signature are used for verification, not just the zero terminated string. Therefore it is recommended that all file signatures are padded with zeros to fill the 16 bytes. See the Dbfversion service for the format of the version numbers. The offset within the file of the first record is to allow additional information to be added to the header (called the Extended Header). Note that the first record will always be a type 2 record - see below. The data consists of records, each with a 2 byte header stored as a word. The high nibble of the most significant byte (i.e. the 2nd byte in the record) gives the record's type. This can take the following values: 0 A deleted record. 1 A main record. 2 The Field Information Record. 3 The Descriptive Record. 4-7 Reserved for record types which won't be merged. 8 - 13 Reserved for record types which will be merged. 14 Reserved for voice entries. 15 Used internally (not to be used by applications). Note that types 8 - 14 will be copied and merged by the pbfcopyFile service when DbfRecordTypeAl1l is specified whereas record types 3 - 7 will only be copied if the target file is created, i.e. not if merging two files. The remaining 12 bits of the header word give the size of the record. However the maximum size of a record is 4094 bytes, so that there is room in a 4096 byte buffer for the longest record including its header. The Field Information Record is used to store the field structure used by the other records. There will be exactly | Field Information Record per file and it will always be the first record in the file (any other type 2 records will be ignored). Each byte in the record indicates the type of the corresponding field in the records which follow, so the length of this record is the number of fields. The possible values for each byte are: 0 Word 1 Long 20-1 EPOC O/S SYSTEM SERVICES 2 Double 3 String 4 - 255 Reserved The maximum length of this record is 32 bytes representing 32 fields. The 22 byte header and the Field Information Record must be passed to the Dpbfopen service when a file is created or replaced and will be returned by pbfopen when an existing file is opened. Buffering When a database file is opened, the address of a buffer must be provided which should be at least as large as the maximum record size to be used. Thus, a buffer of 4096 bytes is guaranteed to open all database files. This buffer will be used to read this many bytes worth of records from the File System at a time so as to reduce the calls to the File System and vastly increase the speed of operation of most of the DBF services. If the buffer provided is smaller than 4096 and there are records which are longer than the buffer, an error will be given when the file is opened. Note that the read services simply return the offset of the record within the buffer. If the buffer needs to be used by the application, e.g. for editing a record, the DpfcopyDown service should be called to copy the current record to the start of the buffer and to signal that the buffer is invalid. The pbftrash service simply marks the buffer as invalid. These two services will therefore cause the entire buffer to be read in the next time a record is read, inevitably resulting in a loss of performance. All DBF services may overwrite the buffer containing the current record apart from the following: DbfFlush DbfVersion DbfAppend DbfSense Dbf£Count which are guaranteed not to alter the buffer. Index Table In addition to buffering, a sparse index table consisting of a 4 byte address for every 16 records will be constructed when the file is opened to increase the speed of random access to the file. As records are added to the file, the table will also be appended. When a record is deleted, each pointer in the table after the deleted record will be moved to the next record, so that they always point to every 16th record. Note that the index table will reside in a different segment so as not to use up the application's space. End of file record When any of the record services attempt to read past the end of the file, zofzrr will be returned and the current record number will be the number of the last record plus 1. Also, attempting to read before the first record in the file, either with the DpfBackRead Service or the DbffrindRead Service searching backwards will result in zofErr and the current record number will be zero (i.e. the first record if there is one). However the offset in the buffer of the first/last record will not be returned, when £ofeErr is returned. The "current record" is always given by the record number returned by the pbfsense service but if any service gives EofErr, the current record will be the last record number plus | - this is called the end of file record (unless the error is caused by going before the first record). When this is the case, any services which work on the current record, e.g. DbfEraseRead, DbfUpdate, DbfFindRead searching forwards will return EofErr. Similarly if there are no records in the file, ppfsense record will return 0 but the above services will return EofErr. 20 DATABASE FILE MANAGEMENT Number of records The maximum number of records which can be present is 65534 and they are numbered from 0 to 65533. An error will be given by the ppfappend service if an attempt is made to write more than 65534 records. DbfOpen Open a database file CL Type of record. SI Pointer to the main buffer. DI State. Dx Length of the main buffer. BX Points to a DbfopenkEnt Structure containing the remaining parameters. RETURN: Carry clear DI State. RETURN: Carry set RecordErr There are records longer than buffer supplied or buffer length is invalid. InvalidFileErr The file is not a valid DBF file. PANIC: None This service works in the same way as the standard file open service with the following features: e The service can be called in a loop with DI equal to pbfstatestart the first time and then passed as it is returned until it becomes ppbfstatestart again or alternatively if DI is passed as Dbf£StateDisabled, the service will not return until it has finished. Also DI can be passed as pbfst at eOpenNoIndex to disable the building of the index. This means it will be faster to open, but only the following services can be used on a file opened this way: DbfClose, DbfFlush, DbfTrash, DbfCopyDown, DbfCopyFile, DbfAbsRead, DbfAbsReadSense, DbfNextRead, DbfBackRead, DbfFirstRead, DbfSense. Note that reading records non-sequentially will be much slower than when the file is opened with index building. Calls to any other services will produce unpredictable results. e The pbfopenmode field of the ppfopenkEnt structure need not specify the file format. The DBF file format will be assumed. If a file is created or replaced, modeUpdate must be specified since the header is written to the file. e The pbfopenHeader field of the ppfopenknt structure is a pointer to a 56 byte buffer. The header consists of the 22 byte header described above followed immediately by the Field Information Record as a type 2 record. The maximum length of the Field Information Record is 32, plus its 2 byte header = 34. Therefore the buffer must be 22 + 34 = 56 bytes. Even if an Extended Header is required, no gap should be left in the header when creating a file and no gap will be returned when opening an existing file. The file itself, however will contain a gap for the Extended Header, the length of which can be calculated from the 'start of data’ field in the 22 byte header. When opening an existing file, the header buffer must contain the file signature which will be verified against the signature in the file and InvalidrileErr will be returned if it is not identical. Note that all 16 bytes of the signature are always checked, not just the zero terminated string. The remainder of the header buffer will be filled in. Note that the type 2 record is not verified to be the same as the header and so need not be supplied. When creating or replacing a file, the header buffer must contain all 56 bytes to be written to the file as a header. EPOC O/S SYSTEM SERVICES In both the above cases, the minimum version number at offset 20 in the header will be checked and InvalidFileErr returned if this DBF software cannot handle it. See the pbfversion service for the format of the version numbers. Note that only the major version number is checked (i.e. the most significant 4 bits only of the version number word. Also, the type 2 record is checked to be valid and invalidFileErr returned if it is not. e The main buffer at SI is used to read DX bytes worth of records at a time from the File System. e CL specifies the type (0 - 14) of records to be accessed (it will usually be 1). e A sparse index table consisting of a 4 byte address for every 16 records will be constructed when the file is opened to increase the speed of random access to the file. This will reside in a separate segment so as not to use any of the application's space. Note that after opening the file, the current record number will be 0 (as returned by pbfsense) so that a call to DbfNext Read would read record number | in the file and pbfEraseRead would erase record 0. DbfFirstRead should be called to read record 0. The length of buffer supplied must be in the range 512 to 16384. Any length outside this range will result in RecordErr when the file is opened. The maximum length of a record is 4094 bytes, so there is always room in a 4096 byte buffer for all records (including the 2 byte header). DbfClose Close a database file BX The DBF handle to be closed. RETURN: Carry clear Success RETURN: Carry set AL Error number. PANIC: PanicDbf1l BX is not a valid DBF handle. Closes a database file. The handle must be one returned from the ppfopen service. DbfFlush Flush a database file BX The DBF handle. RETURN: Carry clear Success RETURN: Carry set AL Error number. PANIC: PanicDbf1 BX is not a valid DBF handle. Flushes all buffers. DbfTrash Trash a database file BX The DBF handle. RETURN: None PANIC: PanicDbf1 BX is not a valid DBF handle. Signals that the main database file buffer is no longer valid, so that it can be used by an application. See also the Db£fCopyDown Service. 20-4 20 DATABASE FILE MANAGEMENT DbfCopyDown Copy down a DBF record BX The DBF handle. SI The offset into the main buffer of the record to copy down. RETURN: AX The length of the record copied down. PANIC: PanicDbfl BX is not a valid DBF handle. PanicDbf2 SI is not a valid offset. Copies a record at the given offset in the main buffer down to the start of the buffer and sets a flag to signal that the buffer is no longer valid (i.e. there is no need to call ppbftrash). The length of the record is read from the buffer and is returned by the service. DbfCompress Compress a database file BX The DBF handle. DI State. RETURN: Carry clear DI State. RETURN: Carry set AL Error number PANIC: PanicDbf1 BX is not a valid DBF handle. Recovers space used by deleted records provided the file is stored on a compressible media. If the media is not compressible, this service will do nothing and will return carry clear. After calling this service, the current record will be the end of file record (unless the media was not compressible - in which case the current record is unchanged). DI can be passed as pbfStateStart Or DbfStateDisabled. If it is passed as ppfstatestart, the service must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, the service will not exit until it is finished. DbfCopyFile Copy a database file BX The DBF handle. CL Record type to copy. CH The direction of the copy (to or from the target file). Dx Open mode for target file. DI State. SI Pointer to the target file name. RETURN: Carry clear DI State. RETURN: Carry set AL Error number. PANIC: PanicDbfl BX is not a valid DBF handle. Copies records except deleted records from or to the open source file. This service will append records to the end of an existing file if DX is Modeopen or ModeAppend. Note that ModeAppend will perform exactly the same as ModeOpen. Copying with ModeUnique will copy the records to a unique file and return the name in the buffer at SI, in exactly the same way as Dbfopen. Note that the source file can be opened with index building disabled, i.e. with DI as ppfstateopenNoIndex with no loss in performance of the copy. 20-5 EPOC O/S SYSTEM SERVICES CL is used to specify the type of record to be copied. If ppfRecordTypeall is specified, all record types will be copied. Note that when merging files (i.e. DX is Modeopen Of ModeAppend) with DbfRecordTypeA11, only record types | and 8 - 14 will be copied across. Record types 2 - 7 will not be copied. Record type 2 is the Field Information Record and record type 3 is the Descriptive Record and types 4 - 7 are reserved for future use. Record types 2 - 7 will be copied if DX is Modecreate, ModeReplace Of ModeUnique. CH must be passed as pbfCopyFromHandle to copy from the open file to the named file or Dbf£CopyToHandle to copy the other way. Note that in the latter case DX must obviously be passed as Modeopen. Note that it is always slower using DpbfCopyToHandle because of the need to update the index table for the open file. The following procedure is used to implement the copy: e The target file is opened in the mode specified. If copying to an existing file, the signatures of the two files are verified and the r1r's are checked to be compatible. If copying to a new file, the header (including the rrr) and any Extended Header are copied from the source file to the target file. e All records of the specified type are copied from the source file to the target file. e = The target file is closed. e = If any error occurs during the above procedure and the target file has been created by Db£CopyFile, the target file will be deleted, if possible. DI can be passed as DbfStateStart, DbfStateDisabled Of DbfStateCopyAbort: e If it is passed as DbfstateDisabled the service will not exit until it is finished. e If it is passed as pbfstatestart the service must be called repeatedly until state becomes DbfStateStart again. This parameter can be used to plot the progress of the copy, for example by drawing a bar graph. DI will be incremented for every 'buffer size’ number of bytes that are copied (approximately). Hence the scale of the graph can be calculated by dividing the size of the file by the buffer size allocated. The graph plotting procedure must take account of the error in the number of times required to call the service. A fudge factor of 2 should be added to calculate how many times the service will be needed to be called. e Di can be passed as DpbfstateCopyAbort to abort the copy which was started with DbfStateStart. Warning: using DbfCopyFile to merge files can result in a file with more than 65534 records of a particular type in it. When this file is opened with the pbfopen service, only the first 65534 records will be accessible. No error is given from the copy or the open. DbfFileSize Get the size of a DBF BX The DBF handle. RETURN: Carry clear DI:DX The file size in bytes. RETURN: Carry set AL Error number. PANIC: PanicDbfl BX is not a valid DBF handle. Gets the size of an open database file. 20 - 6 DbfExtHeaderRead AL BX ex SI RETURN: Carry clear AX RETURN: Carry set EofErr PANIC: PanicDbf1 20 DATABASE FILE MANAGEMENT Read a DBF extended header 0 to start 1 to continue. The DBF handle. The number of bytes to read. The address of the buffer to receive the data. The number of bytes actually read. The end of the Extended Header has been reached. BX is not a valid DBF handle. Reads CX bytes from the Extended Header of a database file into the buffer supplied. AL must be passed as 0 the first time and 1| to continue. EofErr is returned when the end of the Extended Header is reached, otherwise the actual number of bytes read is returned. DbfExtHeaderWrite AL BX CX SI RETURN: Carry clear AX RETURN: Carry set EofErr PANIC: PanicDbf1 Write a DBF extended header 0 to start 1 to continue. The DBF handle. The number of bytes to write. The address of the buffer containing the data to write. The number of bytes actually written. A write past the end of the Extended Header was attempted. BX is not a valid DBF handle. Writes the buffer supplied into the Extended Header of the file. AL must be passed as 0 the first time and 1 to continue. EofErr is returned when the end of the space allocated for the Extended Header is reached, otherwise the actual number of bytes written is returned. DbfDescRecordRead BX RETURN: Carry clear AX RETURN: Carry set EofErr PANIC: PanicDbf1 Read a DBF descriptive record The DBF handle. The length of the Descriptive Record There is no Descriptive Record in the file. BX is not a valid DBF handle. Reads the Descriptive Record into the main buffer at offset zero. If there is no Descriptive Record, EofErr Will be returned. 20-7 EPOC O/S SYSTEM SERVICES DbfDescRecordWrite Write a DBF descriptive record BX The DBF handle. cx The length of the Descriptive Record to be written. RETURN: Carry clear Success RETURN: = Carry set AL Error number. PANIC: PanicDbf1 BX is not a valid DBF handle. Writes out a Descriptive Record. The record to be written must be stored at the start of the main buffer as a DbfRecord Structure; there must be 2 bytes before the data starts where the record header will be constructed. See pbfAppend. Any existing Descriptive Record will be erased, in other words, there can be a maximum of one Descriptive Record per file. If CX is passed as zero, any existing Descriptive Record Will be erased and no new one will be written out. If there is no Descriptive Record, no error is given. DbfVersion Get the DBF version number None RETURN: AX The DBF version number. PANIC: None Gets the version number of the DBF software. This will be in the form: XYYF where x is the major version number (4 bits) YY is the minor version number (8 bits) F is the release type, either A,B or F for Alpha, Beta or Final respectively (4 bits). For example, if 110FH is returned, the DBF software version is 1.10F. Note that only the major version number is used to determine whether or not the DBF file system can handle a particular file. DbfAbsRead Read an absolute DBF record BX The DBF handle. ex The absolute record number to be read. RETURN: Carry clear AX The length of the record read. SI The offset in the main buffer of the record read. RETURN: Carry set EofErr The requested record number is greater than the number of records in the file. PANIC: PanicDbfl BX is not a valid DBF handle. This service will seek to the given record and read it. Records are read into the buffer (supplied when the file was opened) and the record's offset within the buffer is returned in SI. If the record number requested corresponds to a record beyond the last one, the error zofErr will be returned, the current record will be the end of file record and SI will be invalid. 20-8 DbfAbsReadSense BX CX RETURN: Carry clear AX SI DI:DX RETURN: Carry set EofErr PANIC: PanicDbf1 20 DATABASE FILE MANAGEMENT Read and sense an absolute DBF record The DBF handle. The absolute record number to be read. The length of the record read. The offset in the main buffer of the record read. File position of start of record. The requested record number is greater than the number of records in the file. BX is not a valid DBF handle. Same as the pbfabsRead Service but also returns the file position of the start of the record. DbfNextRead BX RETURN: Carry clear AX SI RETURN: Carry set EofErr PANIC: PanicDbf1 Read the next DBF record The DBF handle. The length of the record read. The offset in the main buffer of the record read. The current record was already the last record in the file. BX is not a valid DBF handle. Seeks to the next record and reads it. Records are read into the buffer (supplied when the file was opened) and the record's offset within the buffer is returned in SI. If the current record is already the last record in the file or there are no records of the current type in the file, EofErr will be returned, the current record will be the end of file record and SI will be invalid. DbfBackRead BX RETURN: Carry clear AX SI RETURN: Carry set EofErr PANIC: PanicDbf1 Read the previous DBF record The DBF handle. The length of the record read. The offset in the main buffer of the record read. The current record was already the first record in the file. BX is not a valid DBF handle. Seeks to the previous record and reads it. Records are read into the buffer provided when the file was opened and the offset into this buffer of the record required is returned in SI. If, on entry to the call, the current record is already the first record in the file or there are no records of the current type in the file, Eofzrr will be returned, the current record will be 0 and SI will be invalid. 20-9 EPOC O/S SYSTEM SERVICES DbfFirstRead Read the first DBF record BX The DBF handle. RETURN: Carry clear AX The length of the record read. SI The offset in the main buffer of the record read. RETURN: Carry set EofErr There are no records in the file. PANIC: PanicDbf1 BX is not a valid DBF handle. Seeks to the first record and reads it. Records are read into the buffer (supplied when the file was opened) and the record's offset within the buffer is returned in SI. If there are no records in the file of the current type, zoferr will be returned, and SI will be invalid. DbfLastRead Read the last DBF record BX The DBF handle. RETURN: Carry clear AX The length of the record read. SI The offset in the main buffer of the record read. RETURN: Carry set EofErr There are no records in the file. PANIC: PanicDbf1l BX is not a valid DBF handle. Seeks to the last record and reads it. Records are read into the buffer (supplied when the file was opened) and the record's offset within the buffer is returned in SI. If there are no records in the file of the current type, zofErr will be returned, and SI will be invalid. DbfAppend Append a DBF record BX The DBF handle. CX The length of the record to be appended. RETURN: Carry clear Success RETURN: = Carry set OverFlowErr There are already 65534 records in the file. RecordErr The total length of the record (including the 2 byte header) is greater than the length of the main buffer. PANIC: PanicDbfl BX is not a valid DBF handle. This service appends a record of the current type to the end of the file and makes this the current record. The record to be written must be placed at the start of the main buffer as a pbfRecord structure which is defined as: typedef struct { UWORD header; /* Used for record header word */ UBYTE data[2]; /* Data to be written... * f } DbfRecord; The header word will be used to construct the header for the record so that it can be written in one. CX is the length of the data only. 20 - 10 20 DATABASE FILE MANAGEMENT DbfEraseRead Erase a DBF record BX The DBF handle. DI State. RETURN: Carry clear AX The length of the record read. SI The offset in the main buffer of the record read. DI State. RETURN: Carry set EofErr The current record is the end of file record. PANIC: PanicDbf1 BX is not a valid DBF handle. Erases the current record and reads the next one. A record is erased by overwriting its (4 bit) type to 0. The space used by the record can only be recovered by calling ppfcompress. The file must be stored on a compressible medium. If there are no records of the current type in the file or if the current record number is the last record plus 1, EofErr will be returned. If the current record is the last record in the file, it will be erased and zofErr will be returned. Note that pbfEraseRead may return EofErr in 2 different circumstances: e If the current record is already the end of file record (or there are no records). e If the current record is the last record. In the first case, the service does nothing. In the second case, the last record is erased and the current record becomes the end of file record. It is up to the application to deduce which of these cases has occurred by checking whether the current record is the end of file record before calling the service (using DbfSense and DbfCount) or by noting the decrease in the total number of records from pbfcount. DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppfstateDisabled, the service will not exit until it is finished. DbfUpdate Update a DBF record BX The DBF handle. CX The length of the record to be written. DI State. RETURN: Carry clear DI State. RETURN: Carry set EofErr The current record is the end of file record. PANIC: PanicDbf1 BX is not a valid DBF handle. Erases the current record and appends the new one to the end of the file making this the new current record. The new record to be appended will be taken from the beginning of the main buffer. The main buffer must begin with a word where the record header will be built, followed by the record itself. CX is the length of the data only and does not include the word at the start. Note that the current record will only be erased after the supplied record has been successfully appended. If there are no records of the current type in the file or if the current record number is the last record plus 1, EofErr will be returned. If the current record is the last record in the file, it will be erased and £oferr will be returned. 20 - 11 EPOC O/S SYSTEM SERVICES DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, the service will not exit until it is finished. DbfFindRead Find a DBF record AL The number of fields to search. BX The DBF handle. Cx The length of the buffer to match. DL The maximum field length to match with. DH The type and direction of the search. DI State. SI Pointer to the match buffer. RETURN: Carry clear AX The length of the record read. DI State. SI The offset in the main buffer of the record read. RETURN: Carry set EofErr No matching record was found. PANIC: PanicDbfl BX is not a valid DBF handle. PanicDbf2 Parameters are invalid. Matches the given wild-card string with the string components of each record starting at the current record. If the current record is the end of file record, EofErr will be returned, unless DH specifies DbfFindBackwards. If a match is found, the record containing the match is made the current record and is read into the buffer; the offset will be returned in SI. AL specifies how many string fields are to be searched (the number of string fields in the Field Information Record is now irrelevant). A value of DpfFindAllstrings must be used to specify continue matching string fields until the end of the record is reached. The Field Information Record Is used to specify the 'types' of the first 32 fields. After that, all fields are assumed to be strings until the end of the record. DL specifies the maximum length of a string field to be used in the match, i.e. longer strings are truncated for matching purposes. 255 specifies no truncation. DH is split into 2 halves. The most significant nibble of DH specifies the type of match and must be one of the following: DbfFindCaseIndependent Case independent match. Dbf£fFindCaseDependent Case dependent match. The least significant nibble of DH specifies the search direction and must be one of the following: DbfFindForwards Search forwards from current record to next match. DbfFindBackwards Search backwards from current record to previous match. DbfFindFirst Search to first match in file. DbfFindLast Search to last match in file. If a match is not found, zoferr will be returned and SI will be invalid. The current record will then be the first record if the search was backwards or the last record number plus one (the end of file record) if the search was forwards. The Field Information Record contains the record structure which is used to find the string components of the record. This is always passed to pbfopen as part of the header when a file is created and is returned when an existing file is opened. DI can be passed as pbfStateStart OF DbfStateDisabled. If it is passed as ppfstatestart, the service must be called repeatedly until state becomes ppfstatestart again. If it is passed as ppbfstateDisabled, the service will not exit until it is finished. 20 - 12 20 DATABASE FILE MANAGEMENT DbfSense Sense the current DBF record number BX The DBF handle. RETURN: AX The current record number. PANIC: None Sense the current record number. This will be the last record number plus 1 if an EofErr has just been given (unless there are no records, in which case it will be 0). DbfCount Count the number of DBF records BX The DBF handle. RETURN: AX The number of records of the current type. PANIC: None Returns the number of records in the file of the current type. It will not alter the current record number. ©DbfFindReadField Find a DBF record by field AL The number of fields to search. BX The DBF handle. cx The length of the buffer to match. DL The maximum field length to match with. DH The type and direction of the search. DI State. SI Pointer to the match buffer. DatEClassPtr The starting field from which to search (0 for first field) RETURN: = Carry clear AX The length of the record read. DI State. SI The offset in the main buffer of the record read. RETURN: Carry set EofErr No matching record was found. PANIC: PanicDbfl BX is not a valid DBF handle. PanicDbf£2 Parameters are invalid. Matches the given wild-card string with the string components of the specified fields in each record starting at the current record. If the current record is the end of file record, FofErr will be returned unless DH specifies pbfFindBackwards. This service is the same as DbfFindRead except that DatEClassPtr specifies the starting field from which the search starts (with 0 specifying the first field). For example, to search only the third, fourth and fifth text fields, set patEClassPtr to 2 and AL to 3. 20 - 13 20 - 14 CHAPTER 21 HARDWARE MANAGEMENT HwComboOn Switch on the combo None RETURN: None PANIC: None This service will switch on the combo hardware subsystem (CHS) if not already switched on. Although the CHS has been enabled, it can be accessed either by an external expansion device or by Asicl. If it is desired to access the CHS using Asicl then the SLDTX bit in the Asic! Control register needs to be enabled as well. Before turning the CHS on, it is important to see if it is available for use by calling the HwGet Combo service. This service is equivalent to HwComboOnInput for all variants except Asic9 variants (Series 3a). On Asic9 variants HwComboOn puts the codec into output mode, while HwcComboonInput puts it into input mode. HwComboOftf Switch off the combo None RETURN: None PANIC: None This service will switch off the combo hardware subsystem (CHS) if not already switched off. HwPacksOn Switch on the SSDs None RETURN: None PANIC: None This service will switch on the SSD subsystem (SSDS) if not already switched on. This service is provided for the built in SSD drivers and should not be called by any other drivers or applications. HwPacksOff Switch off the SSDs None RETURN: None PANIC: None This service will switch off the SSD subsystem (SSDS) if not already switched off. This service is provided for the built in SSD drivers and should not be called by any other drivers or applications. 21-1 EPOC O/S SYSTEM SERVICES HwSetA2Control1Bits Set bits Asic2 register 1 AL Mask of bits to be set. RETURN: None PANIC: None This service can be used to set bits in Asic2 control register 1. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit which is set in the mask will cause the corresponding bit in the control register to be set. HwClearA2Control1 Bits Clear bits Asic2 register 1 AL Mask of bits to be cleared. RETURN: None PANIC: None This service can be used to clear bits in Asic2 control register 1. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit which is set in the mask will cause the corresponding bit in the control register to be cleared. HwReadA2Control1 Read Asic2 register 1 None RETURN: AL The value currently in control register 1. PANIC: None This service can be used to read Asic2 control register 1. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it returns the value in its up-to-date copy. HwWriteA2Control1 Write Asic2 register 1 AL The new value to be written to control register 1. RETURN: None PANIC: None This service can be used to write to Asic2 control register 1. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. HwSetA2Control2Bits Set bits Asic2 register 2 AL Mask of bits to be set. RETURN: None PANIC: None This service can be used to set bits in Asic2 control register 2. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit set in the mask will cause the corresponding bit in the control register to be set. 21-2 21 HARDWARE MANAGEMENT HwClearA2Control2Bits Clear bits Asic2 register 2 AL Mask of bits to be cleared. RETURN: None PANIC: None This service can be used to clear bits in Asic2 control register 2. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit set in the mask will cause the corresponding bit in the control register to be cleared. HwReadA2Control2 Read Asic2 register 2 None RETURN: AL The value currently in control register 2. PANIC: None This service can be used to read Asic2 control register 2. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it returns the value in its up-to-date copy. HwWriteA2Control2 Write Asic2 register 2 AL The new value to be written to control register 2. RETURN: None PANIC: None This service can be used to write to Asic2 control register 2. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. HwSetA2Control3Bits Set bits Asic2 register 3 AL Mask of bits to be set. RETURN: None PANIC: None This service can be used to set bits in Asic2 control register 3. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit set in the mask will cause the corresponding bit in the control register to be set. HwClearA2Control3Bits Clear bits Asic2 register 3 AL Mask of bits to be cleared. RETURN: None PANIC: None This service can be used to clear bits in Asic2 control register 3. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Each bit set in the mask will cause the corresponding bit in the control register to be cleared. 21-3 EPOC O/S SYSTEM SERVICES HwReadA2Control3 Read Asic2 register 3 None RETURN: AL The value currently in control register 3. PANIC: None This service can be used to read Asic2 control register 3. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it returns the value in its up-to-date copy. HwWriteA2Control3 Write Asic2 register 3 AL The new value to be written to control register 3. RETURN: None PANIC: None This service can be used to write to Asic2 control register 3. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. In effect, it updates the value in its up-to-date copy and then writes to the Asic2 register. HwSelectChannel Select a serial channel AL The new channel to be selected. RETURN: AL The channel that was previously selected. PANIC: None This service will select which channel the serial controller in Asic2 will be connected to for subsequent serial data transfers. This service is necessary because the operating system cannot read directly from Asic2 and must keep its own up-to-date copy of the register contents. Interrupt service routines which use the serial controller must re-select the channel that was previously selected. This can be achieved by saving the value returned in AL when this service is called, as it is the currently selected channel. HwNullFrame Send a serial null frame None RETURN: None PANIC: None This service is useful for sending a null frame to a serial channel. This is important in order to guarantee that the controller and the slave device attached to the channel are synchronised. HwSwitchOff Switch off cx The number of quarter seconds to switch off for. RETURN: None PANIC: None This service may be called to switch off the machine. In fact, the machine is never truly switched off and can wake up again in order to service an event in the future. The value in CX determines how many quarters of a second must pass before the machine will wake up again. If the value in CX is less than or equal to 8 then this service will do nothing. 21-4 21 HARDWARE MANAGEMENT If an absolute timer is pending or a process is sleeping until an absolute time then the value in CX will be adjusted to make sure that the machine wakes up in time to service the outstanding timer or to wake up the process. If the value in CX is OxFFFF then the machine will just switch off until an outstanding absolute time event is ready to expire or until the user switches on the machine. The IBM PC version of EPOC does not support this service; instead, the HwExit service can be called which will return to DOS. HwExit Exit to DOS None RETURN: None PANIC: None This service is only available on the IBM PC version of Epoc/Os and will exit from the operating system and return to DOS. HwGetCombo Capture the combo subsystem None RETURN: = Carry clear Success RETURN: Carry set InUseErr The combo subsystem is already captured. PANIC: None This service acts as a gate to the combo subsystem so that two device drivers do not both try to access the combo subsystem at the same time. After capturing the combo subsystem, it must be released by calling the Hwrreecombo service when no longer required HwFreeCombo Free the combo subsystem None RETURN: None PANIC: None This service will free the combo subsystem after it has been captured with the HwGet combo service. HwGetChannel Get a channel AL The mask of the channels being captured. RETURN: Carry clear Success. RETURN: = Carry set InUseErr The channel is already captured. PANIC: None This service provides a gate to control access to the hardware interrupt service routines. It is also a handy way of ensuring that two device drivers do not start talking to the same expansion port at the same time, by getting the channel which is associated with that expansion port. The strategy is to request the channel before trying to talk to the hardware. If the channel is allocated successfully, then all is well and the driver can then talk to the expansion port. Whenever a driver has captured a channel in this way it must free the channel when it is no longer required by calling the HwFreeChannel Service. 21-5 EPOC O/S SYSTEM SERVICES HwFreeChannel Free a channel AL The mask of the channels being freed. RETURN: None PANIC: None This service will free a channel after it has been captured with the HwGetChannel service. HwGetPsuType Get the power supply type None RETURN: AL The power supply type. PANIC: None There are two power supply variants in the MC range of computers which use the EPOC operating system. Consequently there are two version of the operating system due to the different power supply handling code. Apart from this service, EPOC hides the differences between the two power supplies. The REPRO software which will load a new operating system into the FLASH memory uses this service to know which version of EPOC to load. HwGetSupplyStatus Get supplies status SS:BX Pointer to a SupplyEnt structure. RETURN: None PANIC: None This service may be used to get the current status of the various supplies. The value returned for the main battery and lithium batteries are in millivolts. The MainsPresent field can be: <0 mains status cannot be determined at the current time (if the SSD doors are open) 0 mains is not present 1 mains is present HwSupplyWarnings Get supplies warnings SS:BX Pointer to a SupplyWarningsEnt Structure. RETURN: None PANIC: None This service may be used to ask the operating system what the maximum value of the main and lithium battery reading can be and what an appropriate warning level would be. The values in the structures are in the same units as for the HwGet SupplyStatus, 1.e. millivolts. This service will return different values depending on the battery type set with the censetBatteryType service. If no battery type is set then the values for an alkaline battery will be returned. HwLcdContrastDelta Change the LCD contrast AL +ve to step contrast up. -ve to step contrast down. RETURN: None PANIC: None This service can be used to step the LCD contrast up or down depending on whether AL is positive or negative. 21-6 21 HARDWARE MANAGEMENT HwReadLcdContrast Get current LCD contrast None RETURN: AL The current contrast value. PANIC: None This service can be used to get the current contrast setting. HwSetBackLight Set backlight control BX The new backlight control value. RETURN: None PANIC: None This service can be used to set the backlight control. The value in BX contains two values. The bottom 15 bits are a time-out in ticks (1/32nd of a second) to switch off the backlight. If this value is zero then the backlight is not switched off automatically. The top bit (i.e. the sign bit), is used to enable/disable the operating system from toggling the backlight state on reception of the backlight key. Setting the bit will disable the operating system. HwGetBackLight Get backlight control None RETURN: AX The backlight control value. PANIC: None This service can be used to get the current backlight control value. HwBackLight Operate the backlight AL 0 - Switch off the backlight. 1 - Switch on the backlight. 2 - Toggle the backlight. 3 - Return the backlight state. RETURN: Carry clear AL The previous or current backlight state: 0 - backlight is/was off. 1 - backlight is/was on. RETURN: Carry set Not SupportedErr Machine does not support a backlight. PANIC: None This service can be used to perform the following functions: e Switch the backlight on and off. e =6Toggle the backlight state. e Query the current backlight state. A backlit version of the machine can be determined by checking for the Not supportErr being returned with AL = 3 to query the backlight state. 21-7 EPOC O/S SYSTEM SERVICES ©HwGetScanCodes Scan the state of all keys BX Pointer to 10 word array to take the scan codes. RETURN: Nothing. PANIC: None Writes values to the array at BX corresponding to the state of each key on the keyboard and to each application button. A unique bit is set for each key being pressed when this service is called. If the key is up then no bit is set. On the Series 3a, eleven bits are valid in each of the first eight words and the Workabout uses nine bits in each of the first eight words. On HC machines, eight bits in ten words are valid. This service is not available on the MC400, MC200 and Series 3. The set of scan codes is different for each machine's keyboard layout, but is fully determined by the position of the key on each type of machine. The following diagrams specify the scan code associated with each key on the different machines which support this service. Each box represents a key. The first number in each box gives the element of the array at BX used for that key (first element 0), and the second number gives the hexadecimal mask which, when anped with that array element, gives a non-zero result if that key is down. For example, on a Series 3a if the Control key is being pressed, element 2 of the array anped with hex 80 is non-zero. Series 3a keyboard HC alphabetic keyboard 0,080 6,040 7,040 Note that the scan code (0, 080) given for the On/Off key is that for Off. The scan codes for On (8,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. 21-8 21 HARDWARE MANAGEMENT The Off scan code is received if the application captures the Off key (capture of this key by the HC Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide) HC numeric keyboard 0,080 6,040 7,040 0,020 3,001 3,002 3,004 3,008 0,010 6,020 1,004 1,008 1,010 5,002 6,002 5,001 0,040 0,004 0,008 5,010 5,008 5,004 7,002 0,001 Note that the scan code given for the On/Off key (0, 080) is that for Off. The scan codes for On (g,080 - not shown in the above diagram) and Off (0, 080) are not normally received by application code. The Off scan code is received if the application captures the Off key (capture of this key by the HC Command Shell must first be disabled - see the Command Shell chapter of the HC Programming Guide). Workabout keyboard C= 3,040 4,040 5,040] |6,040 oa 6.020 7,020 0,040 1,040 eS 2,020 3,020 4,020 5,020 6,010 7,010 0,020 1,020 2,010 3,010 4,010 5,010 (— 6, 008 7,008 0,010 1,010 NG 0,00 1,00 2,00 3,00 4,00 5,00 2,004 3,004 4,004 5,004 6,004 7,004 4,004 5,002 6, 002 7,002 0,004 1,004 0,00] 1,004 0,004 1,004 2,002 3,002 ( > 2,001 4,00] 5,00] S S (— ay 3,001 6,00] 7,00] X S 21-9 EPOC O/S SYSTEM SERVICES Note that the scan code given for the On/Esc key (0,100) is the Escape scan code. The scan codes for On (0, 080 - not shown in the above diagram) and Off (6, 020) are not normally received by application code. The Off scan code is received if the application captures the Off key. ©HwComboOninput Switch on the combo in input mode None RETURN: None PANIC: None This service is equivalent to HwComboon for all variants except Asic9 variants (Series 3a). On Asic9 variants HwComboon turns on the codec and puts it into output mode. HwcomboOnInput also turns on the codec but puts it into input mode. ©HwSupplyinfo Get additional power supply data BX Pointer to supplyInfokEnt structure RETURN: Nothing. PANIC: None. Write information concerning the various power supplies to the supplyInfokEnt structure at BX. This information can be used to monitor battery and mains usage. Only Asic9 variants (Series 3a) return meaningful data. The supplyInfoknt structure is defined in epocsibo.inc. Hardware Management update The majority of the additional EPOC hardware management system services described in this section were introduced for the Series 3c and Siena. With the exception of the HC, all the services are, in principle, available on any machine that contains EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in this section should generate an =_GEN_NsuP error. Some services require the presence of hardware that is not built into all machines in the SIBO range. If the relevant hardware is not present on a particular machine, calling the service will either have no effect or return an error of —_GEN_Nnsup. The descriptions of such services contain a list of the machines on which they are intended to be used. HwResetBatteryStatus Reset the battery status None RETURN: None PANIC: None Reset the battery status information. This service has the same effect as replacing the main batteries. HwEnableAutoBatReset Enable/disable battery info reset BX Enable/disable/query the status RETURN: AL The current auto battery reset status, if queried, otherwise none. PANIC: None This service is primarily intended for use on the Workabout. Enable or disable an auto reset of the battery information when the battery is recharged in-place. The value of BX should be 1 to enable, 0 to disable, or -1 to query the auto reset status. If querying the status, a value of lor 0 is returned in AX, respectively meaning that auto reset is enabled or disabled. 21-10 21 HARDWARE MANAGEMENT HwGetBatData Return battery information None RETURN: AX Pointer to battery information. PANIC: None Return the address of the supplyInfoEnt battery information structure in the OS data segment. The structure is defined as: SupplyInfoEnt struc SuMainBat Level db ? SuMainBatStatus db ? SuBackupBatLevel db ? SuDcLevel db ? SuWarningFlags dw ? SuInsertionDate dd 2 SuTicksInUseBattery dd ? SuTicksInUseDc dd ? SuMilliampTicks dd ? SupplyInfoEnt ends This structure is equivalent to the PLIB &_suppLy_inro struct. HwReLogPacks Relog the SSDs None RETURN: = Carry clear Success RETURN: = Carry set AL Error number PANIC: None Relog the packs. This service has the same effect as opening and then closing the pack doors on a Series 3a. This service is supplied for internal use and is not intended to be called by application code. HwSetiRPowerLevel Set the IR power level BX Required power level RETURN: AX The previous IR power level PANIC: None This service is only available on Series 3c and Siena machines. Set the power level used to drive the IR device to be high or low. BX should be passed as | to set the high power level, or 0 to set the low power level. Return a value (0 for low and 1 for high) representing the IR power level as it was before the service was called. HwReturnTickCount Sense the current tick count None RETURN: AX Tick count. PANIC: None Return, in AX, a value that is incremented on every tick (32 times per second). 21-11 EPOC O/S SYSTEM SERVICES HwReturnExpansionPortState Sense the expansion port state None RETURN: AX Expansion port state. BX At present, always zero. PANIC: None Return the type and current state of the expansion port: The value of AL is non-zero if the pack doors are open. Additionally, on Series 3c machines, it is non zero for a short period after something is plugged into, or removed from, the Honda connector. AH contains one of the following values in its lower three bits: 0x00 Expansion port is Series 3/ Series 3a 6-pin 0x01 Expansion port is Workabout LIF 0x02 Expansion port is Siena Honda 0x03 Expansion port is Series 3c Honda 0x04 Expansion port is HC In addition, the following value may be ored into AH: 0x80 The machine contains the Condor chip HwExpansionOn Enable power to Honda connector None RETURN: None PANIC: None This service is only available on Series 3c machines. Enable the supply of power to a peripheral device connected to the machine via the Honda connector. This service is provided for the built-in SSD drivers and should not be called by any other drivers or applications. HwExpansionOff Disable power to Honda connector None RETURN: None PANIC: None This service is only available on Series 3c machines. Disable the supply of power to a peripheral device connected to the machine via the Honda connector. This service is provided for the built-in SSD drivers and should not be called by any other drivers or applications. 21-12 APPENDIX A INTERRUPT AND FUNCTION NUMBERS Introduction Epoc system services are invoked using the INT nn 8086 instruction. There are two types of system services. e Single - which just do one function. e = Multi - which do more than one function. The multi service functions also require the AH register to be loaded with a value which selects the actual function to be performed. The following section lists the actual numbers associated with the system services and their function numbers. In the listings, names starting with Nm are function numbers and should be placed in AH. All names starting with Nm are made up of Nm followed by a number of name components. The first component after Nm is the name of the interrupt to invoke. For example: NmFilOpen, where Fil is the first name component uses FilManager. NmHeapFreeCell, where Heap is the first name component uses HeapManager. NmDbfClose, where Dbf is the first name component uses DbfManager. MOV AH, NmFilOpen INT FilManager All names not starting with Nm are the names of the single and multi level interrupts. In the documentation, functions are referred to by the name with the leading Nm missing. Thus SegOpen can be called as follows: MOV AH, NmSegOpen INT SegManager Single service interrupts are just referred to by their names. Thus StringLength is called as follows: INT StringLength As usual there are a few exceptions to this rule: e NmLongUnsignedIntRandom is under INT GenManager. NmloOpen is under INT DevManager. EPOC O/S SYSTEM SERVICES Alphabetical list of functions CONVMANAGER NMCONVARGUMENTSTOBUFFER NMCONVFLOATTOBUFFER NMCONVINTI TOBUFFER NMCONVLONGINI NMCONVSTRI NMCONVSTRI NMCONVSTRI NMCONVSTRI NMCONVSTRI NMCONVUNSI NG1 NG1 NG1 NG1 [TTOBUFFER TOF LOAT TOINT TOLONGINT TOUNSIGNEDINT NG1 TOUNS IGNEDLONGINT GNEDINTTOBUFFER NMCONVUNSI DBFMANAGER GNEDLONGINTTOBUFFER NMDBFABSREAD NMDBFABSREADSENSE NMDBFAPPEND NMDBFBACKREAD NMDBFCLOSE NMDBFCOMPRESS NMDBFCOP YDOWN NMDBFCOPYFILE NMDBF COUNT NMDBFDESCRECORDREAD NMDBFDESCRECORDWRITE NMDBFERASEREAD NMDBFEXTHEADERREAD NMDBFEXTHEADERWRITE NMDBFFILESIZE NMDBFF INDREAD NMDBFF INDREADFIELD NMDBFFIRSTREAD NMDBFF LUSH NMDBFLASTREAD EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ OO8AH 0004H 0009H 0002H 0003H OOOAH 0007H 0008H 0005H OO06H OOOOH 0001H OOD8H NM NM NM NM NM NM DBFNEXTREAD DBFOPEN DBFSENSE DBF TRASH DBFUPDATE DBFVERSION DEVMANAGER NM NM NM NM NM NM NM NM NM NM NM NM NM DEVDELETE DEVF IND DEVGETPDDADDRESS DEVHOLD DEVINSTALL DEVLOADLDD DEVLOADPDD DEVOPENPDD DEVQUERYUNITS DEVREMOVE DEVRESUME DEVVECTOR IOOPEN FILMANAGER NMF ILCHANGEDIRECTORY NMF ILCONNECT NMF ILDELETE NMF ILEXECUTE NMF ILLOCCHANGED NMF ILLOCDEVICE NMF ILLOCREADPDD NMF ILMAKEDIRECTORY NMF ILOPENUNIQUE NMF ILPARSE NMF ILPATHGET NMF ILPATHGETBYID EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS OOODH 0000H 0015H 0003H 0013H OOOAH 0085H 0087H EPOC O/S SYSTEM SERVICES NMF ILPATHSET NMFILPATHTEST NMF I LRENAME NMFILSETFILEDATE NMFILSETINITIALPATH NMFILSTATUSDEVICE NMFILSTATUSGET NMFILSTATUSSET NMFILSTATUSSYSTEM NMFILSYSTEMATTACH NMFILSYSTEMDETACH FLOATMANAGER NMFLOATACOS NMF LOATASIN NMF LOATATAN NMFLOATCOS NMF LOATEXP NMF LOATINT NMF LOATLN NMF LOATLOG NMF LOATMOD NMF LOATPOW NMF LOATRAND NMFLOATSIN NMF LOATSQRT NMF LOATTAN GENMANAGER NMGENALARMHOOK NMGENALARMID NMGENALARMUNHOOK NMGENCRC NMGENDEFERREDMODE NMGENENVBUFFERDELETE EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ 0004 0005H 0007 0013H 0012H OO0A 0008 0009H OOOBH OOOE OOOFH 008C oO fo} fo} as r oO oO oO Ww r fo} fo} oO ray r Le fo} oO oO) r fo} fo} fo} ~ r oO fo} oa foo) r fo) fo) fo) aa " 0O8BH 002BH 002DH 002CH 0029H 0008H 0023H NMGENENVBUFFERF IND NMGENENVBUFFERGET NMGENENVBUFFERSET NMGENENVSTRINGDELETE NMGENENVSTRINGF IND NMGENENVSTRINGGET NMGENENVSTRINGSET NMGENGETAMPMTEXT NMGENGETAUTOMAINS NMGENGETAUTOSWITCHOFF VALUE NMGENGETBATTERYTYPE NMGENGETCOMMANDLINE NMGENGETCOUNTRYDATA NMGENGETERRORTEXT NMGENGETLANGUAGECODE NMGENGETNOTIFYSTATE NMGENGETOSDATA NMGENGETRAMSIZEINPARAS NMGENGETSOUNDFLAGS NMGENGETSUFFIXES NMGENGETTEXT NMGENLCDTYPE NMGENMARKACTIVE NMGENMARKNONACTIVE NMGENMASKDECRYPT NMGENMASKENCRYPT NMGENMASKINIT NMGENNOTIFY NMGENNOTIFYERROR NMGENNOTIFYHOOK NMGENNOTIFYUNHOOK NMGENPARSE NMGENPASSWORDCONTROL NMGENPASSWORDQUERY NMGENPASSWORDSET NMGENPASSWORDTEST NMGENRESETREVECTOR EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS EPOC O/S SYSTEM SERVICES NMGENROMVERS ION NMGENSET NMGENSET NMGENSET NMGENSET NMGENSET NMGENSET NMGENSET NMGENSET NMGENSET TAUTOMAINS TAUTOSWITCHOFF VALUE [TBATTERYTYPE [CONFIG TCOUNTRYDATA [NOTIFYSTATE TONEVENTS TREVECTOR TSOUNDF LAGS NMGENSOUND NMGENSTARTREASON NMGENTICKLE NMGENVERSION NMLONGUNSIGNEDINTRANDOM HEAPMANAGER NMHEAPADJUSTCELLSIZE NMHEAPALLOCATECELL NMHEAPCELLSIZE NMHEAPFREECELL NMHEAPFREEMEMORY NMHEAPREALLOCATECELL NMHEAPSETGRANULARITY HWMANAGER NMHWBACKLIGHT NMHWCLEARA2CONTROLIBITS NMHWCLEARA2CONTROL2BITS NMHWCLEARA2CONTROL3BITS NMHWCOMBOOFF NMHWCOMBOON NMHWCOMBOONINPUT NMHWEXIT NMHWFORCESUPPLYREADING EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ 0081 OO8E 0020 0005 0009 000D 0001 0000 0021 0016 001D NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM H WFREECHANNEL WFREECOMBO WGETBACKLIGHT WGETCHANNEL WGETCOMBO WGETPSUTYPE WGETSCANCODES WGETSUPPLYSTATUS WLCDCONTRASTDELTA WNULLFRAME WPACKSOFF WPACKSON WREADA2CONTROL1 WREADA2CONTROL2 WREADA2CONTROL3 WREADLCDCONTRAST WSELECTCHANNEL WSETA2CONTROLIBITS WSETA2CONTROL2BITS WSETA2CONTROL3BITS WSETBACKLIGHT WSUPPLYINFO WSUPPLYWARNINGS WSWITCHOFF WWRITEA2CONTROL1 WWRITEA2CONTROL2 WWRITEA2CONTROL3 IOMANAGER NM] NM] NM NM] NMI NM NMI OADDAPPLICATIONHANDLER OADDHANDLER IOASYNCHRONOUS OASYNCHRONOUSNOERROR OCLOSE IOENABLEAPPLICATIONHANDLER OENABLEHANDLER EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS OO1A 0018 0086 0015 000B 0000 0001 0010 0017 000D EPOC O/S SYSTEM SERVICES NMI NMI NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] NMI NM] NMI] NM] NM] NM] NM] NM] NMI NM] NM] NM] NM] NM] NM] OKEYANDMO OKEYANDMO ONEXTHALF OPLAYSOUN OPLAYSOUN OPLAYSOUN OREAD ORECORDSO ORECORDSO ORECORDSO OREMOVEAPPLICATIONHANDLER USEASYNCHRONOUS USEWITHWAIT SECOND DA DCANCEL DW UNDA UNDCANCEL UNDW OREMOVEHANDLER OREQUESTRESET OREQUESTRESETCANCEL OROOT OSEEK OSHIFTSTATES OSIGNAL OSIGNALBYPID OSIGNALBYP IDNORESCHED OSIGNALKILLASYNCHRONOUS OSIGNALKILLCANCEL OSUPER OWAITFORS OWAITFORS IGNAL IGNALNOHANDLER OWAITFORSTATUS OWITHWAIT OWRITE OYIELD IOSERMANAGER NM] NM] NM] NM] NM] OSERADDHANDLER OSERATTACHONOPENCHAN OSERCANCELALLSIGNALUSER OSERCANCELIOREQUEST OSERCHECKREADSI EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ 001C 0014 OODE 0001 0O00D 0O01C 001B 0011 NM] NM] NM NM] NM] NM NM] NM] NM NM] NM] NMI NM] NM] NM] NM] NMI NM] NM] NM] NM] NM] NM] NM] NMI NM] NM] OSERCHECKWRITESI OSERCLOSETIMERHANDLER IOSERDETACHFREE OSERFREE OSERHANDLERSAVEERROR IOSERONOPENCHAN OSEROPEN OSEROPENHANDLER IOSEROPENT IMERHANDLER OSERQUEUEREAD OSERQUEUESUPER OSERQUEUETIMER OSERQUEUEWRITE OSERREMOVEHANDLER OSERSENSEONOPENCHAN OSERSETHANDLER OSERSIGNALCOMPLETE OSERS IGNALCOMP LETEOK OSERSIGNALUSER OSERS IGNALUSERREAD OSERS IGNALUSERREADOK OSERSIGNALUSERWRITE OSERSIGNALUSERWRITEOK OSERSYNCWRITE OSERTIMERCANCEL OSERTIMERCLOSE OSERTIMEROPEN LIBMANAGER NMLI NMLI NMLI NMLI BCOPY BCREATE IBCREATEBYHANDLE IBDESTROY IBFIND BHANDLE BLINK EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS 0084 0008 0005 0006 0007 0003 0004 0002 EPOC O/S SYSTEM SERVICES NMLIBLOAD EQU OOOOH NMLIBLOADFILE EQU OOOAH NMLIBOPEN EQU 0009H NMLIBRECLASS EQU OOOBH NMLIBRECLASSBYHANDLE EQU OOOCH NMLIBUNLOAD EQU 0001H MES SMANAGER EQU 0083H NMMESSFREE EQU 0007H NMMESSINIT EQU OOOOH NMMESSRECEIVEAS YNCHRONOUS EQU 0001H NMMESSRECEIVECANCEL EQU 0003H NMMESSRECEIVEWITHWAIT EQU 0002H NMMESSSEND EQU 0004H NMMESSSENDRECEIVEAS YNCHRONOUS EQU 0005H NMMESSSENDRECEIVEWITHWAIT EQU OO006H NMMESSSIGNAL EQU 0008H NMMESSSIGNALCANCEL EQU 0009H NMMESSSIGNALCANCELX EQU OOOAH PROCMANAGER EQU 0088H NMP ROCCREATE EQU 0004H NMPROCCREATETASK EQU 0005H NMPROCF IND EQU OOOBH NMP ROCGETOWNER EQU 0010H NMPROCGETPRIORITY EQU 0002H NMPROCID EQU OOOOH NMPROCIDBYNAME EQU 0001H NMPROCKILL EQU 0008H NMP ROCNAMEBY ID EQU OOOAH NMPROCONTERMINATE EQU OOOEH NMPROCPANICBYID EQU 0009H NMP ROCRENAME EQU OOOCH NMP ROCRESUME EQU OO006H NMPROCSETPRIORITY EQU 0003H A-10 A INTERRUPT AND FUNCTION NUMBERS NMP ROCSUSPEND EQU OOO07H NMPROCTERMINATE EQU OOODH NMPROCWATCHALLEXITS EQU OOOFH SEGMANAGER EQU 0080H NMSEGADJUSTSIZE EQU OO006H NMSEGCLOSE EQU 0004H NMSEGCLOSELOCKEDORDEVICE EQU OOODH NMSEGCOP YFROM EQU 0009H NMSEGCOPYTO EQU 0008H NMSEGCREATE EQU 0001H NMSEGDELETE EQU 0002H NMSEGF IND EQU OO007H NMSEGFREEMEMORY EQU OOOOH NMSEGLOCK EQU OOOAH NMSEGOPEN EQU 0003H NMSEGRAMDISKUSED EQU OOOCH NMSEGSIZE EQU 0005H NMSEGUNLOCK EQU OOOBH SEMMANAGER EQU 0082H NMSEMCREATE EQU OO00H NMSEMDELETE EQU 0001H NMSEMS IGNALMANY EQU 0004H NMSEMSIGNALONCE EQU 0003H NMSEMS IGNALONCENORESCHED EQU 0005H NMSEMWAIT EQU 0002H TIMMANAGER EQU 0089H NMTIMDATETODAYSECONDS EQU 0007H NMT IMDAYOFWEEK EQU 0009H NMTIMDAYSECONDSTODATE EQU OO06H NMTIMDAYSECONDSTOSYSTEMTIME EQU 0005H NMTIMDAYSINMONTH EQU 0008H EPOC O/S SYSTEM SERVICES w w w w w w NMTIMGETSYSTEMTIME NMT IMNAMEOFDAY NMT IMNAMEOFDAYABB NMT IMNAMEOFMONTH NMT IMNAMEOFMONTHABB NMTIMSETSYSTEMTIME NMTIMSLEEPFORTENTHS NMTIMSLEEPFORTICKS NMTIMSYSTEMT IMETODAY SECONDS NMTIMWAITABSOLUTE NMT IMWEEKNUMBER UFFERCOMPARE UFFERCOMPAREFOLDED UFFERCOPY UFFERJUSTIFY UFFERLOCATE UFFERLOCATEFOLDED UFFERMATCH UFFERMATCHFOLDED UFFERSUBBUFFER UFFERSUBBUFFERFOLDED UFFERSWAP HARISALPHABETIC HARISALPHANUMERIC HARISCONTROL HARISDIGIT HARISGRAPHIC HARISHEXDIGIT HARISLOWERCASE HARISPRINTABLE HARISPUNCTUATION HARISSPACE HARISUPPERCASE HARTOFOLDEDCHAR HARTOLOWERCHAR HARTOUPPERCHAR EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ DUMMY F LOATADD F LOATCOMPARE FLOATDIVIDE FLOATMULTIPLY FLOATNEGATE FLOATSUBTRACT FLOATTOINT F LOATTOLONG FLOATTOUNSIGNEDINT F LOATTOUNS IGNEDLONG GENDATASEGMENT GENINTBYNUMBER NTTOFLOAT OKEYANDMOUSESTATUS ONEXTHALFSECONDSTATUS LIBENTER LIBENTERSEND LIBLEAVE LIBSEND LIBSENDEXACT LIBSENDEXIT LIBSENDSUPER LONGINTCOMPARE LONGINTDIVIDE LONGINTMULTIPLY LONGTOF LOAT LONGUNS IGNEDINTCOMPARE LONGUNSIGNEDINTDIVIDE LONGUNSIGNEDINTMULTIPLY PROCCOPYFROMBYID PROCCOPYTOBYID PROCINDSTRINGCOPYFROMBYID PROCPANIC STRINGCAPITALISE STRINGCOMPARE STRINGCOMPAREFOLDED EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS OOCFH OOBBH OOBDH OOBCH OOCDH OOBEH OOCOH OOBFH 0091H 0092H OODCH 0090H OODBH OOAFH OOBOH EPOC O/S SYSTEM SERVICES STRINGCONVERTTOFOLDED STRINGCOPY STRINGCOPYFOLDED STRINGLENGTH STRINGLOCATE STRINGLOCATEFOLDED STRINGLOCATEINREVERSE STRINGLOCATEINREVERSEFOLDED STRINGMATCH STRINGMATCHFOLDED STRINGSUBSTRING EQU STRINGSUBSTRINGFOLDED STRINGVALIDATENAME UNSIGNEDINTTOFLOAT UNSIGNEDLONGTOFLOAT WSERVFUNCTIONS EQU WSERVOPCODES Numerical list of functions SEGMANAGER NMSEGFREEMEMORY NMSEGCREATE NMSEGDELETE NMSEGOPEN NMSEGCLOSE NMSEGSIZE NMSEGADJUSTSIZE NMSEGF IND NMSEGCOPYTO NMSEGCOP YFROM NMSEGLOCK NMSEGUNLOCK NMSEGRAMDISKUSED NMSEGCLOSELOCKEDORDEVICE EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ D6H OOAEH OOACH OOADH OOB9H 00B3H OOB4H OOB5H OOB6H 0OB1H OOB2H OOB8H OOBAH OOCCH OOCEH 008DH 0080H 0000H 0001H 0002H 0003H 0004H 0005H OO06H OO0O07H 0008H 0009H OOOAH OOOBH OOOCH OOODH A INTERRUPT AND FUNCTION NUMBERS HEAPMANAGER EQU 0081H NMHEAPALLOCATECELL EQU OOOOH NMHEAPREALLOCATECELL EQU 0001H NMHEAPADJUSTCELLSIZE EQU 0002H NMHEAPFREECELL EQU 0003H NMHEAPCELLSIZE EQU 0004H NMHEAPSETGRANULARITY EQU 0005H NMHEAPFREEMEMORY EQU OO06H SEMMANAGER EQU 0082H NMSEMCREATE EQU OOOOH NMSEMDELETE EQU 0001H NMSEMWAIT EQU 0002H NMSEMS IGNALONCE EQU 0003H NMSEMS IGNALMANY EQU 0004H NMSEMS IGNALONCENORESCHED EQU 0005H MES SMANAGER EQU 0083H NMMESSINIT EQU OOOOH NMMESSRECEIVEASYNCHRONOUS EQU 0001H NMMESSRECEIVEWITHWAIT EQU 0002H NMMESSRECEIVECANCEL EQU 0003H NMMESSSEND EQU 0004H NMMESSSENDRECEIVEASYNCHRONOUS EQU 0005H NMMESSSENDRECEIVEWITHWAIT EQU OO06H NMMESSFREE EQU 0007H NMMESSSIGNAL EQU 0008H NMMESSSIGNALCANCEL EQU 0009H NMMESSSIGNALCANCELX EQU OOOAH LIBMANAGER EQU 0084H NMLIBLOAD EQU 0O00H NMLIBUNLOAD EQU 0001H EPOC O/S SYSTEM SERVICES NMLIBLINK NMLIBF IND NMLIBHANDLE NMLIBCREATE NMLIBCREATEBYHANDLE NMLIBDESTROY NMLIBCOPY NMLIBOPEN NMLIBLOADFILE NMLIBRECLASS NMLIBRECLASSBYHANDLE DEVMANAGER NM NM NM NM NM NM NM NM NM NM NM NM NM IOOPEN DEVOPENPDD DEVGETPDDADDRESS DEVINSTALL DEVHOLD DEVRESUME DEVLOADLDD DEVLOADPDD DEVDELETE DEVQUERYUNITS DEVF IND DEVREMOVE DEVVECTOR IOMANAGER NM] NM] NM NM] NM] NM NMI A- 16 OASYNCHRONOUS OASYNCHRONOUSNOERROR IOWITHWAIT OROOT OSUPER IOWAITFORSIGNAL OWAITFORSTATUS EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ 0085H OO000H 0001H 0002H 0003 0004 0005H 0006 0007 0008H 0009 OO0A OOOBH 000C 0086H 0000 0001H 0002H 0003 0004H 0005 0006 NM] NM] NM] NM] NMI NM] NM] NM] NMI NM] NM] NM] NM] NM] NM] NM] NMI NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] NM] OYIELD OSIGNAL OSIGNALBYPID OSIGNALBYP IDNORESCHED OADDHANDLER OREMOVEHANDLER OENABLEHANDLER OREQUESTRESET OREQUESTRESETCANCEL OCLOSE OREAD OWRITE OSEEK OKEYANDMOUSEWITHWAIT OADDAPPLICATIONHANDLER OREMOVEAPPLICATIONHANDLER OENABLEAPPLICATIONHANDLER OSHIFTSTATES OWAITFORS IGNALNOHANDLER OSIGNALKILLASYNCHRONOUS OSIGNALKILLCANCEL OKEYANDMOUSEAS YNCHRONOUS ONEXTHALF SECOND OPLAYSOUNDA OPLAYSOUNDW OPLAYSOUNDCANCEL ORECORDSOUNDA ORECORDSOUNDW ORECORDSOUNDCANCEL FILMANAGER NMF ILCONNECT NMF ILEXECUTE NMF ILPARSE NMF ILPATHGET NMF ILPATHSET EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS 0087 0000 0001 0002 0003 0004 EPOC O/S SYSTEM SERVICES NMFILPATHTEST EQU 0005H NMF ILDELETE EQU OO006H NMF I LRENAME EQU O007H NMFILSTATUSGET EQU 0008H NMFILSTATUSSET EQU 0009H NMFILSTATUSDEVICE EQU OOOAH NMFILSTATUSSYSTEM EQU OOOBH NMF ILMAKEDIRECTORY EQU OOOCH NMF ILOPENUNIQUE EQU OOODH NMFILSYSTEMATTACH EQU OOOEH NMFILSYSTEMDETACH EQU OOOFH NMF ILPATHGETBYID EQU 0010H NMF ILCHANGEDIRECTORY EQU 0011H NMFILSETINITIALPATH EQU 0012H NMFILSETFILEDATE EQU 0013H NMF I LLOCCHANGED EQU 0014H NMF ILLOCDEVICE EQU 0015H NMF ILLOCREADPDD EQU 0016H PROCMANAGER EQU 0088H NMPROCID EQU 0O000H NMPROCIDBYNAME EQU 0001H NMPROCGETPRIORITY EQU 0002H NMPROCSETPRIORITY EQU 0003H NMP ROCCREATE EQU 0004H NMP ROCCREATETASK EQU 0005H NMP ROCRESUME EQU OO06H NMP ROCSUSPEND EQU OO007H NMPROCKILL EQU 0008H NMPROCPANICBYID EQU 0009H NMP ROCNAMEBY ID EQU OOOAH NMPROCF IND EQU OOOBH NMP ROCRENAME EQU OOOCH NMPROCTERMINATE EQU OOODH NMPROCONTERMINATE EQU OOOEH NMPROCWATCHALLEXITS EQU OOOFH NMP ROCGETOWNER EQU 0010H A-18 TIMMANAGER NMTIMSLEEPFORTENTHS NMTIMSLEEPFORTICKS NMTIMGETSYSTEMT IME NMTIMSETSYSTEMTIME NMTIMSYSTEMT IMETODAY SECONDS NMTIMDAYSECONDS1 NMTIMDAYSECONDS1 TOSYSTEMTIME TODATE NMTIMDATETODAYSECONDS NMTIMDAYSINMONTH NMT IMDAYOFWEEK NMT IMNAMEOFDAY NMT IMNAMEOFMONTH NMTIMWAITABSOLUTE NMT IMWEEKNUMBER NMT IMNAMEOFDAYABB NMT IMNAMEOFMONTHABB CONVMANAGER NMCONVUNSIGNEDINTTOBUFFER NMCONVUNSIGNEDLONGINTTOBUFFER NMCONVINTTOBUFFER NMCONVLONGINTTOBUFFER NMCONVARGUMENTSTOBUFFER NMCONVSTRINGTOUNSIGNEDINT NMCONVSTRINGTOUNS IGNEDLONGINT NMCONVSTRINGTOINT NMCONVSTRINGTOLONGINT NMCONVFLOATTOBUFFER NMCONVSTRINGTOFLOAT GENMANAGER NMGENVERSION NMGENLCDTYPE EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS 0089H 0O000H 0001H 0002H 0003H 0004H 0005H 0006H OO007H 0008H 0009H OOOAH OOOBH O0O00CH OOODH OOOEH OOOFH OO8AH OO8BH 0O000H 0001H EPOC O/S SYSTEM SERVICES NMGENSTARTREASON NMGENPARSE NMLONGUNSIGNEDINTRANDOM NMGENGETCOUNTRYDATA NMGENGETERRORTEXT NMGENGETOSDATA NMGENDEFERREDMODE NMGENNOTIFY NMGENNOTIFYERROR NMGENNOTIFYHOOK NMGENNOTIFYUNHOOK NMGENGETRAMSIZEINPARAS NMGENGETCOMMANDLINE NMGENGETSOUNDFLAGS NMGENSETSOUNDFLAGS NMGENSOUND NMGENMARKACTIVE NMGENMARKNONACT!I NMGENGETTEXT NMGENGETNOTIFYS1 NMGENSETNOTIFYS1 NMGENGETAUTOSWIT NMGENSETAUTOSWIT NMGENSETREVECTOR VE TATE TATE [CHOFF VALUE [CHOFF VALUE NMGENRESETREVEC1 TOR NMGENGETLANGUAGECODE NMGENGETSUFFIXES NMGENGETAMPMTEXT NMGENSETCOUNTRYDATA NMGENGETBATTERYTYPE NMGENSETBATTERYTYPE NMGENENVBUFFERGET NMGENENVBUFFERSET NMGENENVBUFFERDELETE NMGENENVBUFFERF IND NMGENENVSTRINGGET NMGENENVSTRINGSET EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS NMGENENVSTRINGDELETE EQU 0027H NMGENENVSTRINGF IND EQU 0028H NMGENCRC EQU 0029H NMGENROMVERS ION EQU O002AH NMGENALARMHOOK EQU 002BH NMGENALARMUNHOOK EQU 002CH NMGENALARMID EQU 002DH NMGENPASSWORDSET EQU 002EH NMGENPASSWORDTEST EQU O002FH NMGENPASSWORDCONTROL EQU 0030H NMGENPASSWORDQUERY EQU 0031H NMGENTICKLE EQU 0032H NMGENSETCONFIG EQU 0033H NMGENMASKINIT EQU 0034H NMGENMASKENCRYPT EQU 0035H NMGENMASKDECRYPT EQU 0036H NMGENSETONEVENTS EQU 0037H NMGENGETAUTOMAINS EQU 0038H NMGENSETAUTOMAINS EQU 0039H FLOATMANAGER EQU 008CH NMFLOATSIN EQU OO00H NMF LOATCOS EQU 0001H NMF LOATTAN EQU 0002H NMF LOATASIN EQU 0003H NMF LOATACOS EQU 0004H NMF LOATATAN EQU 0005H NMF LOATEXP EQU OO06H NMF LOATLN EQU 0O007H NMF LOATLOG EQU 0008H NMF LOATSQRT EQU 0009H NMF LOATPOW EQU OOOAH NMF LOATRAND EQU OOOBH NMF LOATMOD EQU OOOCH NMF LOATINT EQU OOODH EPOC O/S SYSTEM SERVICES WSERVOPCODES HWMANAGER NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH NMH WCOMBOON WCOMBOOFF WPACKSON WPACKSOFF WSETA2CONTROLIBITS WCLEARA2CONTROLIBITS WREADA2CONTROL1 WWRITEA2CONTROLI WSETA2CONTROL2BITS WCLEARA2CONTROL2BITS WREADA2CONTROL2 WWRITEA2CONTROL2 WSETA2CONTROL3BITS WCLEARA2CONTROL3BITS WREADA2CONTROL3 WWRITEA2CONTROL3 WSELECTCHANNEL WGETSUPPLYSTATUS WLCDCONTRASTDELTA WREADLCDCONTRAST WSWITCHOFF WNULLFRAME WEXIT WGETCOMBO WFREECOMBO WGETCHANNEL WFREECHANNEL WGETPSUTYPE WSUPPLYWARNINGS WFORCESUPPLYREADING WGETBACKLIGHT WSETBACKLIGHT WBACKLIGHT EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ 008D OO8E 001D OO1E OO1F NMHWCOMBOONINPUT NMHWSUPPLYINFO NMHWGETSCANCODES GENDATASEGMENT PROCPANIC PROCCOPYFROMBYID PROCCOPYTOBYID CHARISDIGIT CHARISHEXDIGIT CHARISPRINTABLE CHARISALPHABETIC CHARISALPHANUMERIC CHARISUPPERCASE CHARISLOWERCASE CHARISSPACE CHARISPUNCTUATION CHARISGRAPHIC CHARISCONTROL CHARTOUPPERCHAR CHARTOLOWERCHAR CHARTOFOLDEDCHAR BUFFERCOPY BUFFERSWAP BUFFERCOMPARE BUFFERCOMPAREFOLDED BUFFERMATCH BUFFERMATCHFOLDED BUFFERLOCATE BUFFERLOCATEFOLDED BUFFERSUBBUFFER w UFFERSUBBUFFERFOLDED w UFFERJUSTIFY STRINGCOPY STRINGCOPYFOLDED STRINGCONVERTTOFOLDED STRINGCOMPARE EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS 0021H 0022H EPOC O/S SYSTEM SERVICES STRINGCOMPAREFOLDED STRINGMATCH STRINGMATCHFOLDED STRINGLOCATE STRINGLOCATEFOLDED STRINGLOCATEINREVERSE STRINGLOCATEINREVERSEFOLDED STRINGSUBSTRING STRINGSUBSTRINGFOLDED STRINGLENGTH STRINGVALIDATENAME LONGINTCOMPARE LONGINTMULTIPLY LONGINTDIVIDE LONGUNS IGNEDINTCOMPARE LONGUNSIGNEDINTMULTIPLY LONGUNSIGNEDINTDIVIDE F LOATADD 7] LOATSUBTRACT 7] LOATMULTIPLY 7] LOATDIVIDE 7] LOATCOMPARE 7] LOATNEGATE 7] LOATTOINT 7] LOATTOUNSIGNEDINT 7] LOATTOLONG 7] LOATTOUNS IGNEDLONG NTTOFLOAT UNS IGNEDINTTOFLOAT LONGTOF LOAT UNS IGNEDLONGTOFLOAT LIBSEND LIBSENDSUPER LIBSENDEXACT LIBENTER LIBLEAVE DUMMY EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ fo} fo} Q ws I fo} oO a ol r oO oO a ~ r fo) (>) Q aa I fo} fo} Q iw) i OOCFH GENINTBYNUMBER WSERVFUNCTIONS LIBSENDEXIT DBFMANAGER NMDBFOPEN NMDBFCLOSE NMDBFF LUSH NMDBF TRASH NMDBFCOP YDOWN NMDBFCOMPRESS NMDBFCOPYFILE NMDBFFILESIZE NMDBFEXTHEADERREAD NMDBFEXTHEADERWRITE NMDBFVERSION NMDBFABSREADSENSE NMDBFABSREAD NMDBFNEXTREAD NMDBFBACKREAD NMDBFFIRSTREAD NMDBFLASTREAD NMDBFAPPEND NMDBFERASEREAD NMDBFUPDATE NMDBFF INDREAD NMDBF SENSE NMDBF COUNT NMDBFDESCRECORDREAD NMDBFDESCRECORDWRITE NMDBFF INDREADFIELD LIBENTERSEND IOKEYANDMOUSESTATUS STRINGCAPITALISE PROCINDSTRINGCOPYFROMBYID EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ A INTERRUPT AND FUNCTION NUMBERS 0OD5 0O0D6 OOD7 00D8 EPOC O/S SYSTEM SERVICES IONEXTHALFSECONDSTATUS IOSERMANAGER NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM NM OSEROPEN OSERADDHANDLER OSERREMOVEHANDLER OSERSETHANDLER OSERHANDLERSAVEERROR OSEROPENHANDLER OSEROPENT IMERHANDLER OSERFREE OSERCLOSETIMERHANDLER OSERDETACHFREE OSERTIMEROPEN OSERTIMERCANCEL OSERTIMERCLOSE OSERATTACHONOPENCHAN OSERSENSEONOPENCHAN OSERONOPENCHAN OSERCHECKWRITESI OSERCHECKREADSTI OSERS IGNALUSERWRITEOK OSERSIGNALUSERWRITE OSERS IGNALUSERREADOK OSERS IGNALUSERREAD OSERS IGNALUSER OSERQUEUEREAD OSERQUEUEWRITE OSERQUEUESUPER OSERQUEUETIMER OSERCANCELIOREQUEST OSERCANCELALLSIGNALUSER OSERS IGNALCOMP LETEOK OSERSIGNALCOMPLETE OSERSYNCWRITE EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ OODD OODE Additional Interrupt and Function numbers A INTERRUPT AND FUNCTION NUMBERS The majority of the additional EPOC system services functions described in this section were introduced for the Series 3c and Siena. With the exception of the HC, all the services are, in principle, available on any machine that contains EPOC version 3.90F or later. On an HC with a suitable version of EPOC, all the functions described in this section should generate an =E_GEN_NsuP error. Some services require the presence of hardware that is not built into all machines in the SIBO range. If the relevant hardware is not present on a particular machine, calling the service will either have no effect or return an error of E_GEN_NSUP. Alphabetical list of extra functions HWMANAGER NMHWENABLEAUTOBATRESET NMHWEXPANSIONOFF NMHWEXPANSIONON NMHWGETBATDATA NMHWRELOGPACKS NMHWRESETBATTERYSTATUS NMHWRETURNEXPANS IONPORTSTATE NMHWRETURNTICKCOUNT NMHWSETIRPOWERLEVEL IOMANAGER NMIOPLAYSOUNDAO Numerical list of extra functions IOMANAGER NMIOPLAYSOUNDAO HWMANAGER NMHWRESETBATTERYSTATUS NMHWENABLEAUTOBATRESET NMHWGETBATDATA NMHWRELOGPACKS NMHWSETIRPOWERLEVEL NMHWRETURNTICKCOUNT NMHWRETURNEXPANSIONPORTSTATE NMHWEXPANSIONON NMHWEXPANSIONOFF EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ EQ aq GaGQaGQGGaGaaGAaaGG GaGa aqqaqaaaqaaG OO8EH 002bH 0033H 0032H 002cH 002eH 002aH 0031H 0030H O02fH 0086H 0024H 0086H 0024H 008EH 002aH 002bH 002cH 002eH OO2fH 0030H 0031H 0032H 0033H APPENDIX B ENVIRONMENT VARIABLES This document is a beta version and is subject to change. This chapter documents all environment variables that, at the time of writing, are created or read by Psion’s software running on SIBO machines. Note that the names of all such environment variables contain the ‘$’ character. Environment variables survive a soft reset but are cleared on a hard reset. Some environment variables will be restored to their default values, by being loaded from a ROM initialisation file, on a hard reset. The set of environment variables that are restored in this way depends on both the machine type and the machine’s localisation (language). PLIB EM$ This environment variable is used by the CLIB and PLIB startup modules. It contains a string that specifies a search path for the 8087 emulator, sys$8087. Idd. Window server $WS_FL On an HC with version 3.5 of the window server, and in all machines that use version 4 or later, the initial value of the internal parameter that is set by wsystem is loaded from the sws_FL environment variable when the window server starts. After setting sws_r1 to the desired worp value, you must reset the HC by pressing the recessed reset button to make the new value effective. The wsystem flags parameter is made up by oring a number of bit fields of the form wsERV_FLAG_Xxx. After a hard reset on an HC with version 3.5 of the window server, the sws_FL environment variable does not exist (which is equivalent to it being zero). The following example program sets the sws_FL environment variable: #include #include GLDEF_C INT main(VOID) { WORD flags; flags=WSERV_FLAG_NO_NOTIFIER_REBOOT |WSERV_FLAG_HOOK_NOTIFIER | WSERV, FLAG LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW; return (p_setenviron("SWS_FL",6,&flags,2))j; } EPOC O/S SYSTEM SERVICES After running this program and resetting the HC, the window server will: e provide the notifier service e report low battery voltages e present a hung-up status window if an application hangs e report a process that terminates with a panic or with a negative reason number $WS_FNTS This environment variable contains a series of words, each of which contains the index of a font used by the window server. The fonts are as follows: e System font e §=6Notifier/Alert font e §=©Status Window font e Symbols font used for the status window diamond symbol e Medium 2 digital clock font e Medium 2 date font e =©Notifier/alert button font e Small status window clock font $WS_IF On the HC, the font used for output that is not graphics context directed is determined by the sws_1F ("Internal Font") environment variable. This should contain a worp binary value of 0 for ws_ront_Base, | for ws_FoNT_BASE+1, and so on. If you change the value of sws_1Fr, you must reset the machine by pressing the recessed reset button to effect the change. The "factory" setting of sws_1F is 4 (which selects the S3 font). $WS_SD Pressing SHIFT-CTRL-PSION-S on an MC, S3, S3a, S3c, Siena or a Workabout saves the current screen to a file called screen.pic in the current path of the window server. Any existing file of the same name is replaced. In practice, the current path of the window server on a SIBO machine is always LOC::M:\ (it is defined when the window server process is started - well before you have any chance of influencing it). However, if an environment variable with the name $WS_SD exists, the window server uses its value to open the file to be created. For example, running the following program: #include GLDEF_C INT main(VOID) { p_setenv ("SWS_SD", "B:\\SCREEN.PIC"); return (0); } subsequently causes the screen dump to be written to the root directory of the local B: drive. If the save fails for any reason (such as disk full), the file is not produced and no notification of the failure is given. You can use this behaviour to disable the SHIFT-CTRL-PSION-S screen dump key by setting up sws_sp to contain an illegal file specification. For example, just inserting the following line of code: p_setenv("SWS_SD",""); disables the screen dump key. B ENVIRONMENT VARIABLES $WS_SF, $WS_SF2 and $WS_SF4 On the HC, the Siena and the Series 3, Series 3a and Series 3c, the system font is determined by the $wWS_SF environment variable which should contain a worp binary value of 0 for ws_rFoNT_BASE, a WORD binary value of | for ws_rontT_BasE+1, and so on. If you change the value of sws_sF, you must reset the machine by pressing the recessed reset button to effect the change. On the MC, the system font is determined in the same way, except that two alternative environment variables are used; sws_sr2 and sws_sr4. If the screen has fewer than 300 lines (as on the MC200), $ws_sF2 is used. Otherwise (as on the MC400), sws_sra is used. The following program illustrates how the environment variable may be changed. #include GLDEF_C INT main(VOID) { WORD flags; flags=1; /* choose WS_FONT_BASE+1 */ return (p_setenviron("SWS_SF",6,&flags,2)); } Changing the system font may have an adverse effect on existing applications. HWIM M$V Evaluator format preferences, stored as an HWIM extTENDED_MEM_VALUES Structure. This environment variable is read and written by the ws_eval_env method of the wssrv class. The default values are: evalDegrees DEGREES_MODE calcDegrees DEGREES_MODE memVal.evalFormat P_DTOB_FIXED memVal.evalDPlaces EVAL_DEFAULT_PLACES memVal.calcFormat P_DTOB_GENERAL memVal.calcDPlaces CALC_DEFAULT_PLACES memVal.values[0] to 0.0 memVal.values[9] D$X Telephone dialling preferences, stored as a DIAL_ENvaR structure. The environment variable is read and written by ws_dial_env method of the wszrv class. The normal default values are: toneLengthTicks 8 delayLengthTicks 8 pauseLengthTicks 48 dialoutCode[] “9,” These values may vary in non-English machines. L$X This environment variable is read by the Series 3c only, to provide a possible extra option for the ‘Use’ choice list of the System Screen’s ‘Communications’ dialog. EPOC O/S SYSTEM SERVICES If it exists, the environment variable should contain three leading byte counted items which are, in order: e text for the extra option, which will be appended to the choice list e the full file specification of the file to p_execc if the new option is selected e any additional command line data For example, to add an ‘IRcom’ option that, on selection, executes the file loc::m:\sys$irc.img, passing it the command line “-P1”, the environment variable could be set (using an HC-style Command Processor).by: set LS$X=\05IRCom\13L0C: :M:\SYSS$IRC.IMG\03-P1 Additional command line options can be appended to any specified in the environment variable by use of the ‘Extra parameters’ line in the System screen’s ‘Communications’ dialog. ees] Printing P$D The type of the port used for printing, held as a zero terminated character containing a single ASCTI digit. The possible port types and their representations are: PRINTER_PORT_PARALLEL ‘0’ PRINTER_PORT_SERIAL ‘Tl PRINTER_PORT_FILE 2’ PRINTER_PORT_FAX ‘3’ The default value represents PRINTER_PORT_PARALLEL. These environment variables are set/created by the pRINTER pr_set_port_type method, and got by the PRINTER pr_port_data method, (see the FORM Reference manual). P$F The name of the print file, that is, the file to which printing is to be directed, held as a zero terminated character string. The default print file name is p.lis. This environment variable is set/created by the PRINTER pr_store_file method, and got by the pRINTER pr_port_data method, (see the FORM Reference manual). P$S The characteristics of the serial port when it is used for printing, held as a p_srcuar structure. The default values are: tbaud P_BAUD_9600 rbaud P_BAUD_9600 frame P_DATA_8 parity 0) hand P_OBEY_XOFF | P_OBEY_DSR|P_IGN_CTS xoff 0x13 xon Ox1l1 flags 0 tmask 0 This environment variable is set/created by the PRINTER pr_store_srchar method, and got by the PRINTER pr_port_data method, (see the FORM Reference manual). B ENVIRONMENT VARIABLES P$M The specification of the current printer model, held as a zero terminated character string. The string contains an ASCII digit, followed by the name of a printer driver (.wdr) file, where the digit specifies the index number, starting from zero, of the particular model within the printer driver file. The default value is “OBJ.WDR’” (the file bj.wdr is present in the ROM of all relevant machines and contains only one model -that for the BJ-10e printer). This environment variable is set/created by the PRINTER pr_set_mode1 method, and got by the pRINTER pr_sense_model method, (see the FORM Reference manual). P$P This environment variable contains two bytes of data that specify the display preferences for print preview. The first byte is an ASCII digit specifying the number of pages to display. This must be in the range ‘1’ to ‘4’ inclusive. The second byte is also an ASCII digit, which may be ‘1’, indicating that margins are to be visible during print preview, or ‘0’. This environment variable is set/created by the prvvIEw wn_init method (see the XADD Reference manual). P$PP The port used for parallel printing, specified as a single ASCII character, for example, ‘B’. This environment variable should only be set on machines that have more than one port, such as the Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the printer class, in the FORM library. P$SP The port used for serial printing, specified as a single ASCII character, for example, ‘A’. This environment variable should only be set on machines that have more than one port, such as the Workabout. It is read if it exists, but is not created, by the pr_sense_port method of the pRintER class, in the FORM library. P$Z The paper size, stored as a single ASCII digit. It is normally ‘0’ (A4) or ‘4’ (Letter). This environment variable is only used on the Siena and the Series 3c. It is not supported on Siena machines with a version number of 4.20 and below. PSIP A single ASCII character, specifying the port letter for the IR printing device. This environment variable is used on the Siena and the Series 3c only. P$PX This environment variable contains the device type and the serial characteristics for ‘Parallel’ printing. It is used only on the Siena and the Series 3c, which communicate with the Parallel cable via a serial interface. The environment variable contains a one byte device type (0 is parallel) followed by a p_srcuar struct, as defined in p_serial.h. EPOC O/S SYSTEM SERVICES Calculator application C$CALC This environment variable is used on the Siena and Series 3c machines only, to store Calculator display preferences. It contains the following structure: typedef struct INT bitmapId; INT currentView; /* store current Calc View */ INT statusWinSize; /* store status window size */ INT nDec; /* -l=off, or 0..4 fixed dec places */ INT Zoom; /* zoom setting for Advanced view */ DOUBLE memory; }CR_CALC_ENV_INFO; whose members have the following meanings: BitmapId for internal use only CurrentView 0=Desk view, 1=Advanced view StatusWinSize one of the Window server flags: w_sTATUS_WINDOW_OFF, W_STATUS_WINDOW_SMALL, or (Series 3c only) w_sTATUS_WINDOW_BIG NDec used by the Desk view: values can be 0 to 4 inclusive, to specify the fixed number of decimal places to display, or -1 to display a variable number of decimal places Zoom used by the Advanced view to contain the ID of the font used in the current zoom state. For the Siena, the allowed range of values is FonT_ID_swiss_s8 to FONT_ID_SWISS_8+3 inclusive, and for the Series 3c the range is FONT_ID_SWISS_8 to FONT_ID_SwWIss_8+4 inclusive Memory the current contents of the Desk view’s memory. M$0MO0 to M$9M9 These environment variables contain the current values of the ten (Advanced view) calculator memories. Note that the names of these environment variables are dependent on the names of the memories, as seen from within the Calculator application. If, for example, memory M2 is renamed to “Memory2”, the environment variable ms2m2 will be replaced by an environment variable with the name ms2mEmory2. The name of each of these environment variables will never exceed eleven characters. Tips application TW$S Contains permanent data for the Tips application. The data consists of a single byte containing two flags: 0x02 if set, the display of tips is enabled 0x04 if set, tips are displayed once per day, otherwise they are displayed whenever the machine is turned on B ENVIRONMENT VARIABLES World application Wsc Contains the display preferences for the World application, as three worps: clock type either wS_CLOCK_FORCE_ANALOG Of WS_CLOCK_FORCE_DIGITAL map colour either TRUE for a grey map or Fa.se for a black map distance units — one of wR_uNITS_MILES (0), WR_LUNITS_KILOMETERS (1) or WR_UNITS_NAUTICAL (2) WS$R This environment variable stores permanent data for the World database services. The content has three elements: e asignature for the world database file, including the file version, e data specifying the home city, e data specifying the default country, that is, the country to which telephone numbers are assumed to belong if a particular country is not specified. Spell/Thesaurus SP$DRV This environment variable identifies the drive that contains the Spellchecker’s global dictionary, as set from the Spell application’s Install menu option. It contains a single ASCII character that may be ‘A’, ‘B’ or ‘M’. SP$OPT This environment variable stores the preferences settings from the Spell application as a series of flags, stored in a single uworp. The contents affect the spellchecker and thesaurus (although not necessarily used by both) The content is an ored combination of the following set of values, selected by the user from the Spell application’s Preferences menu option: 0x0100 if set, ignore words all in upper case 0x0200 if set, ignore words containing punctuation 0x0400 if set, ignore repeated words 0x0800 if set, ignore the case of repeated words 0x1000 if set, show the definitions window WP$SPEL This is used by all applications that may wish to access the Spellchecker. The content is a single byte with a value of zero, but has no significance; the mere existence of the environment variable indicates that the Spellchecker is currently installed. WP$THES This is used by all applications that may wish to access the Thesaurus. The content is a single byte with a value of zero, but has no significance; the mere existence of the environment variable indicates that the Thesaurus is currently installed. EPOC O/S SYSTEM SERVICES ———— ee re] 3Fax application FSX This environment variable contains two bytes of preferences. The first byte contains one of the ASCII characters ‘M’, ‘A’ or ‘B’, representing the drive that is currently used to store the application’s intermediate files. The second byte contains a combination of the following flags: 0x01 if set, a new fax job is created on selection of ‘Print to fax’. Otherwise, the document is simply processed to produce an intermediate file, for later sending 0x02 if set, intermediate files are automatically deleted after they have been sent F$XM Contains the current 3Fax modem parameters. F$XP Stores power usage data for the 3Fax device. Contains the time on batteries and the time on mains. Se ee ee eT) Email applications MAIL$ST This environment variable is used, with some differences in content, by both the Corporate and the Internet PsiMail applications. It is created by an email application whenever a mail session completes, to contain data passed from the message transfer agent (MTA) to the mail client. It is not a permanent store of data, as it is deleted and recreated every time the MTA starts. A MAILSST environment variable created by the Corporate mail application will not disrupt the Internet mail application, should it be run on the same machine, and vice versa. The content for the Corporate application consists of a sequence of five uworns, in the following order: e acount of the messages that were sent e acount of the messages that were received e acount of the messages that were not sent e acount of the messages that are marked as read e¢ a flag which, if set to TRUE, indicates that some messages were not received The content for the Internet application consists of a sequence of eight uworps, in the following order: e acount of the messages that were sent e acount of the messages that were received e acount of the messages that were not sent e acount of the messages that are marked as read e acount of messages that were deleted from the mail server e the return code from the MTA e the return code from the sending process (normally 0) e the return code from the receiving process (normally 0) As can be seen from the above lists, the first four items are common to both variants of MarLsst. B ENVIRONMENT VARIABLES Workabout The following environment variables are used only on Workabout machines. See also pspp and pssp, described in the Printing section of this chapter. S$SVER Contains a text string representing the Workabout Startup Shell version number, for example, “1.00F”. C$P@ This environment variable is set when exiting from the Workabout command processor. It contains a single ASCII character representing the current drive, with a default value of ‘M’. C$PA to C$PZ The environment variable cspa may be set when exiting from the Workabout command processor, to contain a text string representing the current path on drive A. It is not set if the drive A path is to the root directory. Similar environment variables may be set for all other possible drives - cspg to cspz inclusive. C$P£ This environment variable contains the parameters used by Link when accessed from the Workabout System Screen and/or Command Processor. C$P$ This environment variable is set following selection of the keyboard from the Command Processor or the System Screen. It contains a single byte whose binary value is either 0 (Standard keyboard selected) or | (Special keyboard selected). INDEX $WS_FL environment variable, B-1 $WS_FNTS environment variable, B-2 $WS_IF environment variable, B-2 $WS_SD environment variable, B-2 $WS_SF environment variable, B-3 $WS_SF2 environment variable, B-3 $WS_SF4 environment variable, B-3 .wve files sound file format, 8-1 active marking a process, 19-7 unmarking a process, 19-8 add two floats, 14-2 adjust a heap memory cell size, 3-2 size of a memory segment, 2-6 alarm getting the server pid, 19-15 hooking the interface, 19-15 unhooking the interface, 19-15 allocate a heap memory cell, 3-1 re-allocating a heap memory cell, 3-2 am getting the amtext, 19-11 append a DBFrecord, 20-10 arcsine float function, 15-1 arctangent float function, 15-1 asynchronous I/O, 8-2 1/O without error reporting, 8-2 message reception, 5-2 attach a file system, 9-6 auto-switch-off disable/enable if mains present, 19-16 get state if mains present, 19-16 processes and, 19-8 processes and, 19-7 resetting, 19-15 setting value, 19-9 Auto-switch-off Getting value, 19-9 battery enable/disable reset, 21-10 getting type, 19-11 reset the status, 21-10 return pointer to information, 21-11 setting type, 19-11 buffer comparing, 17-1 comparing folded, 17-2 copying, 17-1 justifying, 17-4 locating, 17-2 locating folded, 17-2 subbuffer, 17-3 sub-buffer folded, 17-3 swapping, 17-1 wild card match, 17-3 wild card match folded, 17-4 BufferCompare compare buffers service, 17-1 BufferCompareFolded compare buffers folded service, 17-2 BufferCopy copy buffer service, 17-1 BufferJustify justify a buffer service, 17-4 BufferLocate locate a character in buffer service, 17-2 BufferLocateFolded locate a character in buffer folded service, 17-2 BufferMatch match a wildcard buffer service, 17-3 BufferMatchFolded match a wildcard buffer folded service, 17-4 BufferSubBuffer find a sub-buffer in a buffer service, 17-3 BufferSubBufferFolded find a sub-buffer in a buffer folded service, 17-3 BufferSwap swap buffers service, 17-1 C$CALC environment variable, B-6 C$P$ environment variable, B-9 C$P@ environment variable, B-9 C$PEL environment variable, B-9 C$PA to C$PZ environment variables, B-9 cancel message receive, 5-3 playing back sound file, 8-13 recording sound to file, 8-14 signal from the supervisor, 5-5 signal from the supervisor by type, 5-6 signal from the supervisor I/O, 8-11 capitalising a string, 18-1 EPOC O/S SYSTEM SERVICES category copying data from, 6-7 change size of a memory segment, 2-6 character is a digit, 16-1 is a hexadecimal digit, 16-1 is alphabetic, 16-1 is alphabetic or digit, 16-2 is graphic, 16-3 is lowercase, 16-2 is printable, 16-1 is punctuation, 16-2 is space, 16-2 is uppercase, 16-2 to fold, 16-3 to uppercase, 16-3 Character is control, 16-3 to lowercase, 16-3 CharIsAlpha character is alphabetic service, 16-1 CharIsAlphaNumeric character is alphabetic or digit service, 16-2 CharIsControl character is control service, 16-3 CharIsDigit character is a digit service, 16-1 CharIsGraphic character is graphic service, 16-3 CharIsHexDigit character is a hexadecimal digit service, 16-1 CharIsLowerCase character is lowercase service, 16-2 CharIsPrintable character is printable service, 16-1 CharIsPunctuation character is punctuation service, 16-2 CharIsSpace character is space service, 16-2 CharIsUpperCase character is uppercase service, 16-2 CharToFoldedChar character to fold service, 16-3 CharToLowerChar character to lower service, 16-3 CharToUpperChar character to upper service, 16-3 close a database file, 20-4 afile, 8-8 a locked or device segment, 2-5 a memory segment, 2-4 an I/Odevice, 8-8 coldstart getting the reason for, 19-2 command line getting, 19-6 compare two buffers, 17-1 two buffers case independent, 17-2 two floats, 14-1 two long integers, 13-1 two strings, 18-1 two strings case independent, 18-2 two unsigned long integers, 13-2 compress a database file, 20-5 connect to the file server, 9-1 ConvArgumentsToBuffer convert arguments to buffer service, 12-2 conversion arguments to buffer, 12-2 floating point number to buffer, 12-4 integer to buffer, 12-1 long integer to buffer, 12-2 string to floating point number, 12-5 string to integer, 12-3 string to long integer, 12-3 string to unsigned integer, 12-2 string to unsigned long integer, 12-2 unsigned integer to buffer, 12-1 unsigned long integer to buffer, 12-1 convert a string to folded, 18-1 float to signed integer, 14-3 float to signed long, 14-2 float to unsigned integer, 14-3 float to unsigned long, 14-2 signed integer to float, 14-3 signed long to float, 14-3 unsigned integer to float, 14-3 ConvFloatToBuffer convert floating point number to buffer service, 12-4 ConvintToBuffer convert integer to buffer service, 12-1 ConvLongIntToBuffer convert long integer to buffer service, 12-2 ConvStringToFloat convert string to floating point number, 12-5 ConvStringToInt convert string to integer, 12-3 ConvStringToLongInt convert string to long integer, 12-3 ConvStringToUnsignedInt convert string to unsigned integer, 12-2 ConvStringToUnsignedLongInt convert string to unsigned long integer, 12-2 ConvUnsignedIntToBuffer convert unsigned integer to buffer service, 12-1 ConvUnsignedLongIntToBuffer convert unsigned long integer to buffer service, 12-1 copy a buffer, 17-1 a database file, 20-5 a string, 18-1 a string folded, 18-1 copying down a DBF record, 20-5 data from a process, 10-8 data to a process, 10-9 from a category, 6-7 from a memory segment, 2-7 strings from a process, 10-9 to a memory segment, 2-6 cosine float function, 15-1 count the number of DBF records, 20-13 country data getting, 19-2 setting, 19-2 CRC generating, 19-12 create a memory segment, 2-3 an object by handle, 6-3 an object by number, 6-3 a process, 10-4 a semaphore, 4-1 a task, 10-4 D$xX environment variable, B-3 data segment of the operating system, 19-2 Database file appending a record, 20-10 closing, 20-4 compressing, 20-5 copying, 20-5 copying down a record, 20-5 counting the number of records, 20-13 Deleted records, 20-5 end of file, 20-2 erasing a record, 20-11 file buffering, 20-2 file structure, 20-1 finding a record, 20-12 finding a record by field, 20-13 flushing, 20-4 getting the size, 20-6 Getting the version number, 20-8 index table, 20-2 number of records, 20-3 opening, 20-3 reading an absolute record, 20-8 reading and sensing an absolute record, 20-9 reading the descriptive record, 20-7 reading the extended header, 20-7 reading the first record, 20-10 reading the last record, 20-10 reading the next record, 20-9 reading the previous record, 20-9 sensing the record number, 20-13 trashing the buffer, 20-4 updating a record, 20-11 writing the descriptive record, 20-8 Writing the extended header, 20-7 date abbreviated name of day, 11-5 abbreviated name of month, 11-5 convert date to day seconds, 11-3 convert day seconds to date, 11-3 convert day seconds to system time, 11-3 INDEX convert the system time to day seconds, 11-3 getting am and pm text, 19-11 getting suffixes, 19-11 getting the systemdate, 11-2 name of day, 11-4 name of month, 11-4 number of days in a month, 11-4 set file, 9-8 setting the system date, 11-2 weekday number, 11-4 day abbreviated name of, 11-5 name of, 11-4 days number of, 11-4 DbfAbsRead reading an absolute DBF record service, 20-8 DbfAbsReadSense reading and sensing an absolute DBF record service, 20-9 DbfAppend append a DBF record service, 20-10 DbfBackRead read the previous DBF record service, 20-9 DbfClose closing a database file service, 20-4 DbfCompress compressing a database file service, 20-5 DbfCopyDown copying down a DBF record service, 20-5 DbfCopyFile copying a database file service, 20-5 DbfCount count the number of DBF records service, 20-13 DbfDescRecordRead reading a DBF descriptive record service, 20-7 DbfDescRecord Write writing a DBF descriptive record service, 20-8 DbfEraseRead erasing a DBF record service, 20-11 DbfExtHeaderRead reading a DBF extended header service, 20-7 DbfExtHeaderWrite writing a DBF extended header service, 20-7 DbfFileSize getting the size of a database file service, 20-6 DbfFindRead finding a DBF record service, 20-12 DbfFindReadField finding a DBF recordbyfield service, 20-13 DbfFirstRead read the first DBF record service, 20-10 DbfFlush flushing a database file service, 20-4 DbfLastRead read the last DBF record service, 20-10 iii EPOC O/S SYSTEM SERVICES DbfNextRead read the next DBF record service, 20-9 DbfOpen opening a database file service, 20-3 DbfSense sense the current DBF record number service, 20-13 DbfTrash trashing the DBF buffer service, 20-4 DbfUpdate updating a DBF record service, 20-11 DbfVersion getting the DBF version number service, 20-8 deferred mode setting, 19-4 delete a device driver, 7-3 a file or directory, 9-3 a memory segment, 2-4 a semaphore, 4-1 destroy an object, 6-4 detach a file system, 9-7 DevDelete delete a device driver service, 7-3 DevFind find all devices service, 7-4 DevGetPDDAddress get PDD entry point service, 7-2 DevHold hold all device drivers service, 7-2 devices calling a vector, 7-5 delete a device driver, 7-3 drivers, 7-1 find all devices, 7-4 getting the PDD entry point, 7-2 hold all device drivers, 7-2 install a device driver, 7-2 load a logical device driver, 7-3 load a physical device driver, 7-3 names, 7-1 open a physical device driver, 7-1 query the number of units, 7-4 remove a device driver, 7-4 resume all device drivers, 7-3 devices and files and I/O, 8-1 DevInstall install a device driver service, 7-2 DevLoadLDD load a logical device driver service, 7-3 DevLoadPDD load a physical device driver service, 7-3 DevOpenPDD open PDD service, 7-1 DevQueryUnits query the number of units service, 7-4 DevRemove remove a device driver service, 7-4 DevResume resume all device drivers service, 7-3 DevVector call a device vector, 7-5 directory changing, 9-7 deleting, 9-3 getting status, 9-4 making, 9-6 renaming, 9-4 setting status, 9-4 display type getting, 19-2 divide floats, 14-1 two long integers, 13-1 two unsigned long integers, 13-2 dummy call, 19-3 service, 19-3 DYL getting a handle, 6-3 dynamic library finding, 6-2 getting a handle, 6-3 linking, 6-2 loading, 6-1 loading multiple, 6-6 names, 6-1 unloading, 6-2 EM$ environment variable, B-1 endoffile database file, 20-2 enter a control region, 6-7 leaving from a control region, 6-7 environment variable $WS_FL, B-1 $WS_FNTS, B-2 $WS_IF, B-2 $WS_SD, B-2 $WS_SF, B-3 $WS_SF2, B-3 $WS_SF4, B-3 C$CALC, B-6 C$P$, B-9 C$P@, B-9 C$PE£, B-9 C$PA to C$PZ, B-9 contents and names of all, B-1 D$X, B-3 deleting buffer, 19-13 deleting string, 19-14 EM$, B-1 F$X, B-8 F$XM, B-8 F$XP, B-8 finding buffer, 19-13 finding string, 19-14 getting buffer, 19-12 getting string, 19-14 L$X, B-3 M$0MO, B-6 M$1M1, B-6 M$2M2, B-6 MAILSST, B-8 names and contents of all, B-1 P$D, B-4 P$F, B-4 P$IP, B-5 P$M, B-5 S$SVER, B-9 setting buffer, 19-12 setting string, 19-14 SP$DRV, B-7 SP$OPT, B-7 TW$S, B-6 WSC, B-7 WSR, B-7 WPS$SPEL, B-7 WP$THES, B-7 Environment variable Finding all, 19-13 epocsibo.inc Include file, 21-10 erase aDBFrecord, 20-11 error notificationof, 19-5 errors gettingthetext, 19-3 execute animagefile, 9-1 exits watchingall, 10-8 expansion port sense state of, 21-12 exponentiation floatfunction, 15-2 F$X environment variable, B-8 F$XM environment variable, B-8 F$XP environment variable, B-8 FilChangeDirectory change directory service, 9-7 FilConnect file server connect service, 9-1 FilDelete delete file or directory service, 9-3 filebuffering database file, 20-2 filemanagement attaching a file system, 9-6 INDEX change directory, 9-7 connect to the file server, 9-1 deleting, 9-3 detaching a file system, 9-7 execute a program file, 9-1 get current path, 9-2 get current path by ID, 9-7 getting device status, 9-5 getting status, 9-4 getting system status, 9-5 local file system changed, 9-8 making a new directory, 9-6 parse a filename, 9-2 read a local device directly, 9-9 read media information of a local device, 9-9 renaming, 9-4 set current path, 9-3 set file date, 9-8 set initial path, 9-8 setting status, 9-4 test path available, 9-3 filename generic parse, 19-3 fileserver process, 9-1 filestructure database file, 20-1 FilExecute execute image file service, 9-1 FilLocChanged report if the local file system has changed, 9-8 FilLocDevice read media information of a local device, 9-9 FilLocReadPdd read a local device directly, 9-9 FilMakeDirectory make a new directory service, 9-6 FilOpenUnique I/O open a unique filename service, 9-6 FilParse parse filename service, 9-2 FilPathGet get current path service, 9-2 FilPathGetByld get current path by ID service, 9-7 FilPathSet set current path service, 9-3 FilPathTest test path available service, 9-3 FilRename rename a file or directory service, 9-4 FilSetFileDate set file date service, 9-8 FilSetInitialPath set initial path service, 9-8 FilStatusDevice get device status service, 9-5 FilStatusGet get file or directory status service, 9-4 FilStatusSet setfile or directory status service, 9-4 EPOC O/S SYSTEM SERVICES FilStatusSystem get file system status, 9-5 FilSystemAttach attach a file system service, 9-6 FilSystemDetach detach a file system service, 9-7 find a DBF record, 20-12 a DBF record by field, 20-13 a dynamic library, 6-2 all Devices, 7-4 all processes, 10-7 all segments, 2-6 float adding, 14-2 arc sine function, 15-1 arc tangent function, 15-1 comparing, 14-1 conversion to a buffer, 12-4 converting signed integer to float, 14-3 converting signed long to float, 14-3 converting to signed integer, 14-3 converting to signed long, 14-2 converting to unsigned integer, 14-3 converting to unsigned long, 14-2 converting unsigned integer to float, 14-3 cosine function, 15-1 dividing, 14-1 exponentiation function, 15-2 logarithm function, 15-2 modulo function, 15-3 multiplying, 14-1 natural logarithm function, 15-2 negating, 14-2 power function, 15-3 random number function, 15-3 sine function, 15-3 square root function, 15-4 subtracting, 14-2 tangent function, 15-4 to integer, 15-2 FloatAdd add floats service, 14-2 FloatASin arc sine service, 15-1 FloatATan arc tangent service, 15-1 FloatCompare compare floats service, 14-1 FloatCos cosine service, 15-1 FloatDivide divide floats service, 14-1 FloatExp exponentiation service, 15-2 FloatInt integer service, 15-2 FloatLn natural logarithm service, 15-2 FloatLog logarithm service, 15-2 FloatMod modulo service, 15-3 FloatMultiply multiply floats service, 14-1 FloatNegate negate floats service, 14-2 FloatPow power service, 15-3 FloatRand random number service, 15-3 FloatSin sine service, 15-3 FloatSqrt square root service, 15-4 FloatSubtract subtract floats service, 14-2 FloatTangent tangent service, 15-4 FloatToInt convert float to signed integer service, 14-3 FloatToLong convert float to long service, 14-2 FloatToUnsignedInt convert float to unsigned integer service, 14-3 FloatToUnsignedLong convert float to long service, 14-2 flush a database file, 20-4 free a heap memory cell, 3-3 a message, 5-4 GenAlarmHook hook the alarm interface, 19-15 GenAlarmld get the pid of the alarm server, 19-15 GenCrc generate a CRC check, 19-12 GenDataSegment operating system data segment, 19-2 GenDeferredMode set deferred mode, 19-4 GenEnvBufferDelete delete environment variable, 19-13 GenEnvBufferFind find environment variable, 19-13 GenEnvBufferGet get environment variable, 19-12 GenEnvBufferSet set environment variable, 19-12 GenEnvStringDelete delete environment variable, 19-14 GenEnvStringFind find environment variable, 19-14 GenEnvStringGet get environment variable, 19-14 GenEnvStringSet set environment variable, 19-14 GenGetAmPmText get the am and pm text, 19-11 GenGetAutoMains get state for auto-switch-off if mains present, 19-16 GenGetAutoSwitchOffValue get the auto switch off value, 19-9 GenGetBatteryType get the battery type, 19-11 GenGetCommandLine get the command line, 19-6 GenGetCountryData get country dependent data, 19-2 GenGetErrorText get error text, 19-3 GenGetLanguageCode get the language code, 19-10 GenGetNotifyState get notify state, 19-8 GenGetOsData get O/S data, 19-3 GenGetRamSizelInParas get address able system RAM size, 19-6 GenGetSoundFlags get the sound flags, 19-7 GenGetSuffixes get suffix text, 19-11 GenGetText get operating system text, 19-8 GenIntByNumber interrupt by number, 19-12 GenLcdType LCD type, 19-2 GenMarkActive mark process as active, 19-7 GenMarkNonActive mark process as non-active, 19-8 GenNotify notification service, 19-4 GenNotifyError notification of error, 19-5 GenNotifyHook hook the notifier interface, 19-5 GenParse generic parse, 19-3 GenResetRevector release an interrupt, 19-10 GenRom Version get the ROM version, 19-1 GenSetAutoMains disable/enableauto-switch-off if mains present, 19-16 GenSetAutoSwitchOffValue set the auto switchoff time, 19-9 GenSetBatteryType set the battery type, 19-11 GenSetCountryData set country dependent data, 19-2 GenSetNotifyState set notify state, 19-9 GenSetOnEvents enable/disable on events, 19-16 GenSetRevector capture an interrupt, 19-9 GenSetSoundFlags set the sound flags, 19-7 GenSound make a sound with the piezo, 19-7 GenStartReason getting the system cold start reason, 19-2 INDEX GenTickle reset the autoswitch off timer, 19-15 GenUnAlarmHook unhook the alarm interface, 19-15 GenUnNotifyHook unhook the notifier interface, 19-6 GenVersion operating system version number, 19-1 granularity of the heap memory, 3-3 halfseconds query completion, 8-12 signal on next half second, 8-11 handle of a DYL, 6-3 of a dynamic library, 6-3 handler adding, 8-6 adding an application, 8-9 enabling, 8-6 enabling an application, 8-10 removing, 8-6 removing an application, 8-10 hardware capturing the combo subsystem, 21-5 changing the LCD contrast, 21-6 clearing bits in Asic2 register1, 21-2 clearing bits in Asic2 register2, 21-3 clearing bits in Asic2 register3, 21-3 enable/disable reset, 21-10 exiting toDOS, 21-5 expansion port sense state of, 21-12 freeing a channel, 21-6 freeing the combo subsystem, 21-5 get additional power supply data, 21-10 getting achannel, 21-5 getting backlight control, 21-7 getting current LCD contrast, 21-7 getting supplies status, 21-6 getting supplies warnings, 21-6 getting the power supply type, 21-6 Honda connector power disable, 21-12 Honda connector power enable, 21-12 infrared power level set, 21-11 operating the backlight, 21-7 reading Asic2 register2, 21-3 reading Asic2 register3, 21-4 reset the battery status, 21-10 return battery information, 21-11 scan state of all keys, 21-8 select serial channel, 21-4 sending a serial null frame, 21-4 setting backlight control, 21-7 setting bits in Asic2 register1, 21-2 setting bits in Asic2 register2, 21-2 setting bits in Asic2 register3, 21-3 SSDs relog, 21-11 switching off, 21-4 switching off the combo, 21-1 switching off the SSDs, 21-1 switching on the combo, 21-1 switching on the combo in input mode, 21-10 switching on the SSDs, 21-1 EPOC O/S SYSTEM SERVICES tick count sense current, 21-11 writing Asic2 register 1, 21-2 writing Asic2 register2, 21-3 writing Asic2 register3, 21-4 Hardware Reading Asic2 register1, 21-2 HeapAdjustCellSize adjust heap cellsize service, 3-2 HeapAllocateCell allocate heap cell service, 3-1 HeapCellSize size of heap memory cell, 3-3 HeapFreeCell free a heap cell service, 3-3 HeapFreeMemory size of available heap memory, 3-3 heap memory dynamics, 3-1 HeapReAllocateCell re-allocate heap cell service, 3-2 HeapSetGranularity set heap grow by parameter service, 3-3 Honda connector power disable, 21-12 power enable, 21-12 HwBackLight operating the backlight, 21-7 HwClearA2Control1 Bits clearing bits in Asic2 register 1, 21-2 HwClearA2Control2Bits clearing bits in Asic2 register 2, 21-3 HwClearA2Control3Bits clearing bits in Asic2 register 3, 21-3 HwComboOff switch off the combo, 21-1 HwComboOn switch on the combo, 21-1 HwComboOnInput switch on the combo in input mode, 21-10 HwEnableAutoBatReset enable/disable battery reset on recharge, 21-10 HwExit exit the program, 21-5 HwExpansionOff Honda connector power disable, 21-12 HwExpansionOn Honda connector power enable, 21-12 HwFreeChannel free a channel, 21-6 HwFreeCombo free the combo, 21-5 HwGetBackLight get backlight control, 21-7 HwGetBatData return battery information, 21-11 HwGetChannel get a channel, 21-5 HwGetCombo capture the combo, 21-5 HwGetPsuType get power supply type, 21-6 HwGetScanCodes scan the state of all keys, 21-8 viii HwGetSupplyStatus get supplies status, 21-6 HwLcdContrastDelta change the LCD contrast, 21-6 HwNullFrame send a serial null frame, 21-4 HwPacksOff switch off the SSDs, 21-1 HwPacksOn switch on the SSDs, 21-1 HwReadA2Control1 read Asic2 register 1, 21-2 HwReadA2Control2 read Asic2 register 2, 21-3 HwReadA2Control3 read Asic2 register 3, 21-4 HwReadLcdContrast read current contrast, 21-7 HwReLogPacks relog the SSDs, 21-11 HwResetBatteryStatus reset the battery status, 21-10 HwReturnExpansionPortState expansion port sense state of, 21-12 HwReturnTickCount tick count - sense current, 21-11 HwSelectChannel select serial channel, 21-4 HwSetA2Control1 Bits setting bits in Asic2 register 1, 21-2 HwSetA2Control2Bits setting bits in Asic2 register 2, 21-2 HwSetA2Control3Bits setting bits in Asic2 register 3, 21-3 HwSetBackLight set backlight control, 21-7 HwsSetIRPowerLevel Set the infrared power level, 21-11 HwSupplyInfo get additional power supply data, 21-10 HwSupplyWarnings get supplies warnings, 21-6 HwSwitchOff switch off service, 21-4 HwWriteA2Control1 write Asic2 register 1, 21-2 HwWriteA2Control2 write Asic2 register 2, 21-3 HwWriteA2Control3 write Asic2 register 3, 21-4 V/O adding a handler, 8-6 adding an application handler, 8-9 a synchronous, 8-2 a synchronous without error reporting, 8-2 cancel playing back a sound file, 8-13 cancel recording sound to a file, 8-14 cancel requested reset, 8-7 cancel request for a signal from the supervisor, 8-11 chain to root device, 8-3 chain to super class device, 8-4 closing a device, 8-8 enabling a handler, 8-6 enabling an application handler, 8-10 getting the shift states, 8-10 keyboard and mouse, 8-9 opening a device, 8-7 opening a unique filename, 9-6 play back a sound file asynchronously, 8-12 play back a sound file synchronously, 8-12 polling for completion, 8-5 query the completion of IoNextHalfSecond, 8-12 reading from a device, 8-8 record sound to a file synchronously, 8-13 record sound to file asynchronously, 8-14 removing a handler, 8-6 removing an application handler, 8-10 request a signal the supervisor, 8-11 requesting reset, 8-7 request signal on next half second, 8-11 seeking on a device, 8-8 signalling completion, 8-5 signalling completion by pid with no re-schedule, 8-5 signalling completion by process ID, 8-5 synchronous, 8-3 wait for completion, 8-4 wait for completion no handlers, 8-10 wait for specific completion, 8-4 writing to a device, 8-8 1/O system messaging, 5-2 image opening to access multiplelibraries, 6-5 include file epocdefs.inc, 1-3 indextable database file, 20-2 infrared set power level, 21-11 initialize the message system, 5-2 install adevice driver, 7-2 int by number, 19-12 integer comparing longs, 13-1 comparing unsigned longs, 13-2 conversion to a buffer, 12-1 divide longs, 13-1 divide unsigned longs, 13-2 multiply longs, 13-1 multiply unsigned longs, 13-2 of a float, 15-2 unsigned conversion to a buffer, 12-1 unsigned long random number, 13-3 inter process communications messaging, 5-1 interrupt calling conventions, 1-1 capturing, 19-9 multi service, 1-1 releasing, 19-10 single service, 1-1 INDEX interrupts alphabetic listing, A-2 alphabetic listing - extra functions, A-27 function numbers, A-1 function numbers - extra functions, A-27 numerical listing, A-14 numerical listing - extra functions, A-27 using single or multi, A-1 ToAddHandler I/O add handler service, 8-6 IoApplicationAddHandler I/O add handler service, 8-9 ToAsynchronous I/O asynchronous service, 8-2 ToAsynchronousNoError I/O asynchronous without error reporting service, 8-2 ToClose I/O close a device service, 8-8 IoEnableApplicationHandler 1/O enable/disable application handler service, 8-10 IoEnableHandler I/O enable/disable handler, 8-6 IoKeyAndMouseWith Wait get keyboard and mouse events service, 8-9 IoNextHalfSecond request completion on the next half second, 8-11 ToNextHalfSecondStatus query the completion of Io Next Half Second, 8-12 IoOpen I/O open a device service, 8-7 IoPlaySoundA play back a sound file asynchronously, 8-12 IoPlaySoundCancel cancel playing back a sound file, 8-13 ToPlaySoundW play back a sound file synchronously, 8-12 ToRead I/O read from a device service, 8-8 IoRecordSoundA record sound to a file asynchronously, 8-14 IoRecordSoundCancel cancel recording sound to a file, 8-14 IoRecordSoundW record sound to a file synchronously, 8-13 ToRemoveApplicationHandler I/O remove application handler service, 8-10 ToRequestReset I/O request reset service, 8-7 IoRequestResetCancel I/O cancel requested reset service, 8-7 ToRoot I/O chain to root device service, 8-3 IoSeek I/O seek to a new position, 8-8 ToShiftStates I/O get shift states service, 8-10 ToSignal I/O signal completion service, 8-5 EPOC O/S SYSTEM SERVICES IoSignalByPid I/O signal completion by process ID service, 8-5 IoSignalByPidNoReSched I/O signal completion by pid with no reschedule service, 8-5 IoSignalKillAsynchronous request signal from supervisor service, 8-11 IoSignalKillCancel cancel signal kill from supervisor service, 8-11 IoSuper I/O chain to super class device service, 8-4 ToWaitForSignal I/O wait for completion service, 8-4 IoWaitForSignalNoHandler 1/O wait for completion with no handlers service, 8-10 ToWaitForStatus 1/O wait for specific request to complete service, 8-4 IoWithWait I/O with wait service, 8-3 IoWrite I/O write to a device service, 8-8 IoYield I/O update status words service, 8-5 justify a buffer, 17-4 keyboard reading, 8-9 scanning state of all keys, 21-8 Keyboard scan codes HC alphabetic, 21-8 scan codes HC numeric, 21-9 scan codes Series 3a, 21-8 scan codes Workabout, 21-9 kill aprocess, 10-6 L$X environment variable, B-3 languagecode getting, 19-10 LCD getting the type, 19-2 length of a string, 18-4 LibCopy copy data from a categories segment, 6-7 LibCreate creating an object by number service, 6-3 LibCreateByHandle creating an object by handle service, 6-3 LibDestroy destroying an object service, 6-4 LibEnter enter a control region, 6-7 LibEnterSend send message with an enclosing Lib Enter, 6-5 LibExactSend send message to a known class, 6-5 LibFind dynamic library find service, 6-2 LibHandle dynamic library get handle service, 6-3 LibLeave exit from a control region, 6-7 LibLink dynamic library link service, 6-2 LibLoad dynamic library load service, 6-1 LibLoadFile dynamic library load from multiple library file, 6-6 LibOpen open an image file containing multiple libraries, 6-5 library opening in an image, 6-5 library names dynamic, 6-1 LibReClass() reclassing an object by number, 6-6 LibReClassByHandle reclassing an object by handle, 6-7 LibSend send message to an object service, 6-4 LibSendExit exit from a method, 6-8 LibSuperSend send message to the objects superclass service, 6-4 LibUnLoad dynamic library unload service, 6-2 link a dynamic library, 6-2 load a dynamic library, 6-1 a logical device driver, 7-3 a multiple dynamic library, 6-6 a physical device driver, 7-3 locate a character in a buffer, 17-2 a character in a buffer folded, 17-2 a character in a string, 18-3 a character in a string folded, 18-3 a character in a string in reverse, 18-3 a character in a string in reverse folded, 18-3 lock a memory segment, 2-5 logarithm float function, 15-2 LongIntCompare compare long integers service, 13-1 LongIntDivide long integer divide service, 13-1 longinteger conversion to a buffer, 12-2 unsigned conversion to a buffer, 12-1 LongIntMultiply long integer multiply service, 13-1 LongToFloat convert signed long to float service, 14-3 LongUnsignedIntCompare compare unsigned long integers service, 13-2 LongUnsignedIntDivide unsigned long integer divide service, 13-2 LongUnsignedIntMultiply long unsigned integer multiply service, 13-2 LongUnsignedIntRandom unsigned long integer random number service, 13-3 M$0OMO environment variable, B-6 M$IMI environment variable, B-6 M$2M2 environment variable, B-6 M$3M3 environment variable, B-6 M$4M4 environment variable, B-6 M$5M5 environment variable, B-6 M$6M6 environment variable, B-6 M$7M7 environment variable, B-6 M$8M8 environment variable, B-6 M$9M9 environment variable, B-6 M$V environment variable, B-3 MAIL$ST environment variable, B-8 mark resetting the auto switch off timer, 19-15 match a wildcard buffer, 17-3 a wildcard buffer folded, 17-4 a wildcard string, 18-2 a wildcard string folded, 18-2 media read a local device directly, 9-9 read information of a local device, 9-9 memory adjust heap memory size, 3-2 adjust the size of a memory segment, 2-6 allocate heap memory, 3-1 close a memory segment, 2-4 copy from a memory segment, 2-7 copy to a memory segment, 2-6 create a memory segment, 2-3 delete a memory segment, 2-4 find all segments, 2-6 free heap memory, 3-3 heap memory dynamics, 3-1 lock a memory segment, 2-5 open a memory segment, 2-4 paragraphs size of, 2-1 re-allocate heap memory, 3-2 segment directly accessing, 2-1 segment locking, 2-1 segment names, 2-1 setting the heap granularity, 3-3 size of available heap memory, 3-3 size of available segmented memory, 2-2 INDEX size of addressable system ram, 19-6 size of a heap cell, 3-3 size of a memory segment, 2-5 size of RAM disk, 2-7 unlock a memory segment, 2-5 message enter send, 6-5 sending to a known class, 6-5 sending to an object , 6-4 sending to an objects superclass, 6-4 message reception order of, 5-1 message system I/O system, 5-2 messages asynchronous reception, 5-2 cancelling receive, 5-3 cancel request for a signal from the supervisor, 5-5 cancel request for a signal from the supervisor by type, 5-6 freeing, 5-4 initializing, 5-2 request a signal the supervisor, 5-5 sending, 5-3 sending and getting a reply asynchronously, 5-4 sending and waiting for a reply, 5-4 synchronous reception, 5-3 messaging inter process communication, 5-1 MessFree free message service, 5-4 MessInit initialize messages service, 5-2 MessReceiveAsynchronous receive message asynchronously, 5-2 MessReceiveCancel cancel queued message receive service, 5-3 MessReceiveWith Wait synchronous message reception, 5-3 MessSend send message service, 5-3 MessSendReceiveAsynchronous send message and get reply asynchronously service, 5-4 MessSendReceiveWith Wait send message and wait for reply service, 5-4 MessSignal request signal from supervisor service, 5-5 MessSignalCancelX cancel requested signal from Supervisor by type service, 5-6 method returning from a method, 6-8, 7-1 modulo float function, 15-3 month abbreviated name of, 11-5 name of, 11-4 number of days, 11-4 mouse reading, 8-9 EPOC O/S SYSTEM SERVICES multiply two floats, 14-1 two long integers, 13-1 two unsigned long integers, 13-2 name validation, 18-5 names device, 7-1 memory segments, 2-1 of processes by ID, 10-7 naturallogarithm float function, 15-2 negate floats, 14-2 notify by error number, 19-5 by text messages, 19-4 getting state, 19-8 hooking the interface, 19-5 setting state, 19-9 unhooking the interface, 19-6 number getting suffixes text, 19-11 of week, 11-5 number of records database file, 20-3 object creating by handle, 6-3 creating by number, 6-3 destroying, 6-4 enter a sent message, 6-5 reclassing by handle, 6-7 reclassing by number, 6-6 sending a message, 6-4 sending a message to a known class, 6-5 sending a super class message, 6-4 on events receiving, 19-16 open a database file, 20-3 afile, 8-7 a memory segment, 2-4 a multi library file, 6-5 an I/O device, 8-7 a physical device driver, 7-1 a unique filename, 9-6 operating system data segment getting, 19-2 operating system getting the data, 19-3 operating system text getting, 19-8 owner getting, 10-3 P$D environment variable, B-4 P$F environment variable, B-4 P$IP environment variable, B-5 P$M environment variable, B-5 P$P environment variable, B-5 P$PP environment variable, B-5 P$PX environment variable, B-5 P$S environment variable, B-4 P$SP environment variable, B-5 P$Z environment variable, B-5 panic a process, 10-7 the current process, 10-8 paragraphs size of memory segments, 2-1 parse a filename, 9-2 generic filename, 19-3 path get current, 9-2 get current by ID, 9-7 set current, 9-3 set initial, 9-8 test available, 9-3 PDD physical device driver, 7-1 piezo sound, 19-7 pm getting the pm text, 19-11 polling I/O status words, 8-5 power float function, 15-3 power supply getting additional data, 21-10 priority getting, 10-3 setting, 10-3 ProcCopyFromByld copy data from a process service, 10-8 ProcCopyToByld copy data to a process service, 10-9 ProcCreate create process service, 10-4 ProcCreateTask create task service, 10-4 processes controlling, 10-2 copying data from by ID, 10-8 copying data to by ID, 10-9 copying strings from by ID, 10-9 creating, 10-4 find all, 10-7 get an ID by name, 10-3 get name by ID, 10-7 get owner, 10-3 get priority, 10-3 get the current process ID, 10-2 ID and process table, 10-2 IDs and names, 10-1 killing, 10-6 panicking, 10-7 panicking current, 10-8 renaming, 10-7 resuming, 10-5 scheduling, 10-1 setpriority, 10-3 suspending, 10-5 terminate and kill, 10-2 terminating, 10-6 termination registration, 10-6 watching all exits, 10-8 ProcFind find all processes service, 10-7 ProcGetOwner get the PID of the owning process service, 10-3 ProcGetPriority get process priority service, 10-3 ProclId get current process ID service, 10-2 ProcIdByName get process ID by name service, 10-3 ProcIndStringCopyFromByld copy a string from a process service, 10-9 ProcKill kill process service, 10-6 ProcNameByld name of a process by ID service, 10-7 ProcOnTerminate register termination service, 10-6 ProcPanic panic current process service, 10-8 ProcPanicByld panic process service, 10-7 ProcRename rename a process service, 10-7 ProcResume resume process service, 10-5 ProcSetPriority set process priority service, 10-3 ProcSuspend suspend process service, 10-5 ProcTerminate terminate process service, 10-6 Proc WatchAIIExits monitor exits service, 10-8 query the number of units, 7-4 RAM disk return size of, 2-7 random float function, 15-3 unsigned long integer, 13-3 read a DBF descriptive record, 20-7 a DBF extended header, 20-7 an absolute DBF record, 20-8 from a file, 8-8 from an I/O device, 8-8 the first DBF record, 20-10 the last DBF record, 20-10 the next DBF record, 20-9 the previous DBF record, 20-9 reclass an object by handle, 6-7 an object by number, 6-6 INDEX remove a device driver, 7-4 rename a file or directory, 9-4 a process, 10-7 reset I/O cancel request, 8-7 I/O Request, 8-7 reset system getting the reason for, 19-2 resume a process, 10-5 re-vectors capturing, 19-9 releasing, 19-10 S$SVER environment variable, B-9 Scan codes HC alphabetic, 21-8 HC numeric, 21-9 Series 3a, 21-8 Workabout, 21-9 seek a file to a new position, 8-8 SegAdjustSize adjust the size of a memory segment, 2-6 SegClose close memory segment service, 2-4 SegCloseLockedOrDevice close a locked or device segment, 2-5 SegCopyFrom copy from memory segment service, 2-7 SegCopyTo copyto memory segment service, 2-6 SegCreate create memory segment service, 2-3 SegDelete delete memory segment service, 2-4 SegFind find all segments service, 2-6 SegFreeMemory size of available segmented memory, 2-2 SegLock lock memory segment service, 2-5 segment change size of a memory segment, 2-6 close a memory segment, 2-4 close locked or device, 2-5 copy from a memory segment, 2-7 copy to a memory segment, 2-6 create a memory segment, 2-3 delete a memory segment, 2-4 directly accessing, 2-1 find all segments, 2-6 lock a memory segment, 2-5 locking, 2-1 names, 2-1 size of available segmented memory, 2-2 size of a memory segment, 2-5 unlock a memory segment, 2-5 SegOpen open memory segment service, 2-4 SegRamDiskUsed size of RAM disk service, 2-7 xiii EPOC O/S SYSTEM SERVICES SegSize size of memory segment service, 2-5 SegUnLock unlock memory segment service, 2-5 semaphores creating, 4-1 deleting, 4-1 signalling once without re-schedule, 4-2 signalling more than once, 4-2 signalling once, 4-2 waiting, 4-1 SemCreate create semaphore service, 4-1 SemDelete delete semaphore, 4-1 SemSignal signal once service, 4-2 SemSignalMany signal many service, 4-2 SemSignalOnceNoResched signal once with no re-schedule, 4-2 SemWait wait on semaphore service, 4-1 send a message, 5-3 and get reply asynchronously, 5-4 and wait for reply, 5-4 sense an absolute DBF record, 20-9 the current DBF record number, 20-13 shiftstates Getting, 8-10 signal a semaphore once without re-schedule, 4-2 a semaphore more than once, 4-2 a semaphore once, 4-2 from the supervisor, 5-5 from the supervisor I/O , 8-11 1/O completion, 8-5 1/O completion by pid with no re-schedule, 8-5 1/O completion by process ID, 8-5 SignedIntToFloat convert signed integer to float service, 14-3 sine float function, 15-3 size a database file, 20-6 of addressable systemRAM, 19-6 of a memory segment, 2-5 of a string, 18-4 of systemram, 19-6 sleep a process in system clock ticks, 11-2 a process in tenths of a second, 11-2 a process till a given time, 11-1 sound cancel playing back file, 8-13 cancel recording to file, 8-14 getting the flags, 19-7 play back file (partial) asynchronously, 8-15 play back file asynchronously, 8-12 play back file synchronously, 8-12 record to file asynchronously, 8-14 record to file synchronously, 8-13 setting the flags, 19-7 using the piezo, 19-7 Sound Pitch calculating, 19-7 Sound file names Series 3a ROM, 8-12 sound files format .wve files, 8-1 SP$DRV environment variable, B-7 SP$OPT environment variable, B-7 square root float function, 15-4 SSD relog, 21-11 status of a device, 9-5 of a file or directory, 9-4 of a file system, 9-5 string capitalising, 18-1 comparing, 18-1 comparing folded, 18-2 conversion to float, 12-5 conversion to folded, 18-1 conversion to integer, 12-3 conversion to long integer, 12-3 conversion to unsigned integer, 12-2 conversion to unsigned long integer, 12-2 copying, 18-1 copying folded, 18-1 length, 18-4 locating, 18-3 locating folded, 18-3 locating in reverse, 18-3 locating in reverse folded, 18-3 substring, 18-4 substring folded, 18-4 validate, 18-5 wildcard match, 18-2 wildcard match folded, 18-2 StringCapitalise convert a string to have the first letter uppercase and the rest lowercase service, 18-1 StringCompare comparestrings service, 18-1 StringCompareFolded compare strings folded service, 18-2 StringConvertToFolded convert string to folded service, 18-1 StringCopy copy string service, 18-1 StringCopyFolded copy string folded service, 18-1 StringLength length of string service, 18-4 StringLocate locate a character in string service, 18-3 StringLocateFolded locate a character in string folded service, 18-3 StringLocateInReverse locate a character in a string in reverse service, 18-3 StringLocateInReverseFolded locate a character in string in reverse folded service, 18-3 StringMatch match a wild card string service, 18-2 StringMatchFolded match a wild card string folded service, 18-2 StringSubString find a substring in a string service, 18-4 StringSubStringFolded find a substring in a string folded service, 18-4 String ValidateName validate a system name, 18-5 structures SupplyInfoEnt, 21-11 sub- buffer in a buffer, 17-3 in a buffer folded, 17-3 substring in a string, 18-4 in a string folded, 18-4 subtract floats, 14-2 suffix getting text, 19-11 SupplyInfoEnt Data structure, 21-10 structure, 21-11 suspend a process, 10-5 swap two buffers, 17-1 switching off disable/enable if mains present, 19-16 get state if mains present, 19-16 switching on reporting, 19-16 synchronous V/O , 8-3 message reception, 5-3 tangent float function, 15-4 tasks creating, 10-4 terminate a process, 10-6 termination registration, 10-6 text getting operating system, 19-8 tick count sense current, 21-11 tickle resetting the autoswitch off timer, 19-15 TimDateToDaySeconds convert date to day seconds service, 11-3 TimDayOfWeek day of week service, 11-4 INDEX TimDaySecondsToDate convert day seconds to date service, 11-3 TimDaySecondsToSystemTime convert day seconds to system time service, 11-3 TimDaysInMonth days in month service, 11-4 time convert date to day seconds, 11-3 convert day seconds to date, 11-3 convert day seconds to system time, 11-3 convert the system time to day seconds, 11-3 getting the system time, 11-2 setting the system time, 11-2 sleeping for system clock ticks, 11-2 sleeping for tenths of a second, 11-2 waiting till a given time, 11-1 times absolute and relative, 11-1 TimGetSystemTime get the system time service, 11-2 TimNameOfDay name of day service, 11-4 TimNameOfDayAbb abbreviated name of day service, 11-5 TimNameOfMonth name of month service, 11-4 TimNameOfMonthAbb abbreviated name of month service, 11-5 TimSetSystemTime set the system time service, 11-2 TimSleepForTenths sleep for tenths of a second service, 11-2 TimSleepForTicks sleep for system clock ticks service, 11-2 TimSystemTimeToDaySeconds convert the system time to day seconds service, 11-3 TimWaitAbsolute wait till a given time service, 11-1 TimWeekNumber week number service, 11-5 trash a DBF buffer, 20-4 TW$S environment variable, B-6 unload a dynamic library, 6-2 unlock a memory segment, 2-5 UnsignedIntToFloat convert unsigned integer to float service, 14-3 update a DBF record, 20-11 validate a string, 18-5 vectors calling, 7-5 version of the ROM, 19-1 operating system, 19-1 the DBF version number, 20-8 EPOC O/S SYSTEM SERVICES W$C environment variable, B-7 W$R environment variable, B-7 wait an I/O completion, 8-4 an I/O completion no handlers, 8-10 a process till a given time, 11-1 a specific I/O completion, 8-4 on a semaphore, 4-1 watch all exits, 10-8 week number, 11-5 wildcard buffer match, 17-3 buffer match folded, 17-4 string match, 18-2 string match folded, 18-2 WP$SPEL environment variable, B-7 WPS$THES environment variable, B-7 write a DBF descriptive record, 20-8 a DBF extended header, 20-7 to a file, 8-8 to an I/O device, 8-8 WVE sound files format, 8-1