SIBO 'C' Software Development Kit HC PROGRAMMING GUIDE Version 2.30 March 1, 1999 (C) Copyright Psion PLC 1990-98 All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC, London, England. Reproduction in whole or in part, including utilization in machines capable of reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse engineering is also prohibited. The information in this document is subject to change without notice. Psion and the Psion logo are registered trademarks, and Psion, Psion MC, Psion HC, Psion Series 3, Psion Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of Psion PLC. TopSpeed is a registered trademark of Clarion Software Corporation. IBM, IBM XT and IBM AT are registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer Inc. VAX and VMS are registered trademarks of Digital Equipment Corporation. Brief is a registered trademark of Underware Inc. Psion PLC acknowledges that some other names referred to are registered trademarks. Contents 1 Introduction to the HC............cccsssssssscssscrsssrssersecersserssessessessesssesssssssssseessessessssssssseseesseeeses 1-1 Phe ‘AC: concept sssitiavastesipiist asaya La a aie et seek a 1-1 SWitChiiM OMA OLE seo: 5.2) sug cant ete sk aust sees bet aek Vound oat beeteds weet avn, Hag ace (See sane buted taet ane 1-1 Switching on for the first t1Me........ cele eeseceseeceseeeesseecsseecsseecsseeceseeeesseessaeesseeeees 1-1 PHS Basic hardware’: .vse.ceessoeseces folecedetehedsesvchesepsdetvekesaeh odes sted itt seehedepetet eathawl deseten ete easbedey 1-2 PLOCOSSON oie eceeediseeates big teesedS phase sindess cb steabemiade ech phebbesiodusbinpha degipanee oh Gehh: 1-2 Intertial Memory vee cee eckstest cen piiaees unt cana biodowes tinh ccnethebotss burke eeutaeteast List sen. toubaant iacteeensvs 1-2 Solid state:disks (SSDS) jis.ces.ssesecessees cosesesvccssetes cose susvecsncevoossecuevagaeedeeessh cust cesesvovevancees 1-2 EYP€S*OF SSD a. salar etic: Aetectivedetan esegaeeu tee sin Die a det astra eeatl Meade esata data aterratetes 1-2 Expanision modules: s:..c2.2.e:.sitesiededeiyesibedi gies) ea oehbeipdeed deveined pone Gaede beeepdeed dae 1-3 The Fast Serial port and the Cradle 0.0.0... cee eeeeeeseecsseeceseeeeseeeesaeecsaeessaeesseeesseeeesaes 1-3 Power SUPPLY 4. ccs elie iodo tsaces detente ices As reee aaev ewe eee aia vse Mas even 1-4 Caution regarding lithium batteries... eee eeeeeeseeesneeceneeceeeceseesesaeecsaeessaeesseeeeee 1-4 SCLESN art ey tte he cdste breed ahistetadesteh ade temade veh eievemydanhodaterdene phatase 1-4 WS yDOALC .o Abu Sete tse te tiies cet cae cake tat dee alte cauetnek ah ah react cas Rion tact cat ai ove tee 1-5 THe ‘basic sottwarte iv. siiraiaticet aisianinia is eras ates cen gits len savaine bi limeaganeieiies 1-5 Versions of the HC software ........ceeeescceseccesseecsseecseecsseecesaeeesaeecsaeecseecsseeeesaeessaeers 1-6 The terms Epoc and Plib explained .......... ee eeeeeeseecescecsseeeeseeeeeseecsaeesseecsneeeesaeeesaes 1-6 Graphics Window S€rVer ..........essccsesecssceceseceesececsseecsseeceseecesaeeesaeecsaeecsseeceseeeesaeersaeers 1-6 Multi-taskine kernel .2...sés2inhvhii nial vale inne dine aii 1-6 Support for asynchronous 1/0..........ceesecesseeceseecsseeceseeeesseecsaeecseecsseeeesaeeesaeesseessneeeees 1-7 Database support fUNCtIONS.............cceeeeecceeeesceeeeseneeecseeeeeeseneeeeessaeeeeeenaeeeeneneeeeeeeaeeees® 1-7 Support for remote file ACCESS ......... ees eeseeceseeesseeceseeeesseecsaeecseeceseecesaeeesaeessaeesseeene 1-8 Other ROM-based library services ..........eseceeesessseessseecsseeceseeeesaeecsaeesseessseesesaeessaeers 1-8 Other: ROM Components rey.cc. ea. cu.cevepssnsedep steceds padetbeey latch posuteds pode ses sndes ode y wdebeveveanseae. 1-9 Customising’ an HG. sissies ee agi Sail ahi anal Gail Gained ani 1-9 Hardware Customisation ............:cccesecceseccescecsseecseeceseecesaeeecescecesaeessseeesseecsseeceseeeesaes 1-9 Replacing the built-in Shell oo... eee eeeeeesseccsseecsseecssceceseeceseeeesseecsaeecseesseeseseeeesaes 1-10 Resettins, the: AG 12. cscccetdetocegaseteceesestech pinh eibsestetey pdnhewitaedesotet osthatetedesetebantpetsteterets 1-10 Reproins the-AC 333.3 acsesiniiease ghsieltespaess Gigies eros Bigha eeovheibedapie anes hepae eens 1-11 Master SSDs and mastcpy ...........ceeeccesscecesseceeeecsseecseessseecesaeeesseecsaeecsseeceseeeesaeessaeers 1-12 Once-off ROM customisation Using ROMWTiItC...........eeeesesecsseceseecsneeseneeeesaeeesaeeaes 1-12 Customisation for COPy-ProtectiON ..........escesseccsseeceeeeeseceeseeeesaeecsacecseeeeessseesesaeeesaes 1-12 Connecting to other COMPULETS ........ eee eeeeeeseeeeseecsseeceseecesaeeesaeeeceseecesaeessaeecseessneeeeteeeesaes 1-13 Basics of serial connections to an HC 00.0... eee eeeeeeeeeseeceesseeesaeecsaeecsseecneeesseeesseeeesaes 1-13 RS232) CONNECTIONS 35305 iieeedipsapieele ease hl nelaaebd tii mavnie di die adae airy 1-13 Summary of straightforward usage of Link on the HC .00.... eee eeeeeeseeeseeeeneeeeeeeeeeees 1-13 Why not MS-DOS? racist eniiin ipsa deseyhenela spas ea eek sacs Bnd esp duns Chareeh ess dane SMepeesyeipaas 1-14 2 Writing Software for the HC ................scccsssscssssssccsscssesssscseesssseessscsssssssesessssscsssscseessssssessoees 2-1 Basic programming ChOICES............cccsscccesscceeeeneeeeeseaceceeeacecseeeeceecaeeeeeeeeeesereeseeneeeesseneeeess 2-1 Choice of programming language...........eeeesececcsseessseecsseeessaeeesaeesaeecsaeecsseeeseeeeseeens 2-1 Standard C (Clib) or Psion C (PLD) oo... cccsscccccccesssssneeeeececeseeeeeeeesseesssaeeeseeeesaes 2-1 Writing the User 1Nterface occ: ccc. cio eevee ave ne Bie eucses saved oeesatue cea cousa outecsesudaccecoushecevvuntees 2-2 Synchronous or aSynchronous Processing ..........ssecceseesseeceseeessneecseesseeseecsseeeeseeeesaee 2-3 Example programs. ses: ca. divacdesevcuorssocunctohscsscnsccotsedentns oats bees evoouny odes auussdnheats even voneasetesbovteeday 2-4 A graphics version of Hello World .0..........cccccccesesscceeesnceeceseeeeeeeeeeeesaeeeeesnaeensnneeeenees 2-4 The: Gauge: appl Cation 25 cbse sack. iks ode oh one eis coe ek cake ahd vent nsteet oat int main (void) { puts ("Hello world"); getchar(); return (0); } together with a project file simple.pr #system epoc img #model small jpi #compile simple.c #link simple will run on an HC without any difficulty whatsoever (see the chapter Building an Application in the General Programming Manual for further discussion of TopSpeed .pr project files and their usage). HC PROGRAMMING GUIDE However, it is recommended that HC programmers rewrite the above program as follows: #include #include int main(void) { p_puts ("Hello world"); p_getch (); return (0); } with the project file changed to #system epoc img #set epocinit=iplib #model small jpi #compile simple.c #link simple The latter is said to be the "Plib" version of the former, which is a "Clib" program (the "P" of "Plib" stands for "Psion"). The following differences will be noticed between the two programs: e the Plib program uses Psion-proprietary header files. e the Plib program uses Psion-proprietary function calls (p_xxx functions). e the Plib program links with a different library (this is the significance of the epocinit line in the project file). Code written with Plib calls is considerably more compact than code written with Clib calls. For example the image file for the example Plib program (see above) has size 576 bytes compared with the image file for the equivalent Clib program that has size 4480 bytes - an increase in size of almost seven hundred per cent. The reason for the greater compactness of compiled Plib code is that Plib functions provide only very thin shells for functionality already present in the HC's ROM. Thus Plib calls make more efficient use of the HC ROM software than do the equivalent Clib calls. Being tailored to the particular needs of computers like the HC, Plib evolved with very different constraints and objectives from standard C libraries. In many cases, Plib functions can be claimed to "improve" upon the specification of their nearest Clib equivalents. The use of Plib calls does not always lead to such large space savings as seen in the example programs (see above) - the reduction in the size of the compiled code depends on the number and types of library function calls made. Sometimes it will be desirable to write an application using both Clib and Plib calls simply because this can ease the process of converting large programs to run on the Sibosdk system. The reduced development time will thus outweigh the disadvantages of using the Clib calls. However it is recommended that an application use the Plib library for at least some of its function calls. Although it takes time to become familiar with the Plib library this will repay itself in the form of more compact and powerful applications. Furthermore use of Plib functions is essential for accessing many features of the Sibosdk ROM software - the enhanced graphics facilities of the Window Server for example. Writing the user interface A SIBO interface can be written in one of the following ways: e using console service functions such as p_printf, p_get1, and p_puts or their Clib equivalents. These functions can only produce simple graphical output. They can be extremely useful when debugging an application. e using functions in the Window Server library with the contents of each window backed up with a bitmap. This method is capable of producing a high quality graphical display. e using functions in the Window Server library with the contents of each window explicitly redrawn. This method is capable of creating a high quality graphical display. Use of window redraws is more efficient than use of bitmap backups. 2 WRITING SOFTWARE FOR THE HC The applications programmer does not have to learn to write applications that use the window redrawing mechanism: for many applications backing up the window with a bitmap is sufficient (the penalties of windows with backup bitmaps are much less on the HC screen than on the larger screens of some of the other SIBO computers). The applications programmer who subsequently goes on to learn about window redrawing will not have wasted his/her time learning about window bitmap backups. The latter provide an excellent foundation for the more complex concepts behind window redrawing. The best way to learn graphics programming on the HC is probably to follow the example programs at the end of this chapter and then extend and modify their function. For example one of the example programs illustrates the use of the wInfomsg and wSetBusyMsg functions. These powerful graphics functions display an information message and a flashing busy message respectively at the bottom right corner of the screen. They are hardly more difficult to use than simple console functions such as p_printé and p_puts. Working out how this program and the others work will help to familiarise you with the more commonly used Window Server calls. The example programs and the discussion in this chapter should provide the would-be HC applications programmer with a sufficiently sound base to enable him/her to make effective use of the Window Server Reference manual. Synchronous or asynchronous processing There is a class of programs in which all input to a program comes via the keyboard. These programs can be schematised as follows: Initialise(); FOREVER { ReadKeyFromKeyboard() ; ProcessKey (); } The program terminates in response to a certain pre-defined key. Whilst waiting for a key from the keyboard, the program "hangs", i.e. it is unresponsive to other sources of input. In this case the hanging of the program does not matter as there are no other sources of input. The call ReadkeyFromKeyboard makes what is known as a synchronous read for a key; it is synchronous becomes it does not return until the key it is waiting for has been delivered: the return of the call making the request is automatically synchronised with the delivery of the key. Consider another example of synchronous i/o. In this case, a program that is printing data might be structured (at least in part) as follows: Initialise(); FOREVER { PrepareLineToPrint (); SendLineToPrinter (); } This program loop terminates when there is no more data to print. Now the process of sending a line of data to the printer might take some time. The printer buffer could be full in which case the program would have to wait for the buffer to empty a bit before being able to prepare the next line for printing. Thus the call sendLineToPrinter could be synchronous (this is the way beginner programmers would tend to write the code), with the program "hanging" in the call until the printer has removed the data passed to it by the program. In this state, the program is, again, unresponsive to other sources of input. In either of the above examples, a simple extension of the code would require the synchronous call to become asynchronous. The printing program could and should be extended to allow the user to terminate the printing while in progress by simply pressing a predefined key. The key-processing program could be extended so as to respond to a timer expiring (for example a signal to commence a backup procedure). Many programmers approach this kind of generalisation in an ad hoc manner resulting in spaghetti like code that is hard to debug, hard to maintain and hard to extend. Such code will usually force the user to wait while it is waiting for one or more events. The user can thus be shut out for significant periods of time. 2-3 HC PROGRAMMING GUIDE The software on the HC has been explicitly designed to address these issues. For all but the simplest of programs the concept of asynchronous events is central to successful programming on the HC: would-be applications writers are strongly urged to face up to this issue squarely, from the beginning. This may sound daunting (and it probably would be daunting, on alternative software platforms), but for two reasons, it is not: e the HC operating system software has carefully isolated the various components involved in asynchronous i/o: signals, semaphores, "status words", and "active words" (amongst others) e example programs in the Fundamental Programming Guidelines chapter of the General Programming Manual survey these components in a thorough yet straightforward manner. Example programs There are example programs scattered throughout the length and breadth of the SDK. It is recommended that, whenever possible, would-be HC applications developers should take the time to try out these examples, and to modify them. As in all fields, practice makes perfect - and it is always possible to get an idea from the detail of one of these programs, which will prove helpful in a quite different coding situation. The three programs to be discussed in this chapter have particular relevance to the HC. They demonstrate its graphics potential, and show how to create line editors to allow convenient data entry by end users of the HC (whereas Series3 and Series3a programmers can use the Hwif library to obtain easy access to line editors and other related user interface objects, there is at the time of writing no corresponding library for the HC - so programmers have to take care of the user interface by themselves). These examples build on those discussed in the General Programming Manual, and it is suggested that any readers who have not yet worked through that manual carefully should do so now, before proceeding any further. In contrast with the examples in the General Programming Manual, which only use console i/o, the example programs in this chapter all interact more directly with the Window Server. The source code for all these examples is located in \sibosdk\demo. Incidentally, these programs can also be made to run, with minor modifications, on Series3 and Series 3a machines. A graphics version of Hello World The first example is a short program stored as w_hello.c: #include #include GLDEF_C INT main(VOID) { WS_EV event; wStartup(); gBorder (W_BORD_CORNER_4) ; wSetBusyMsg ("Hello world",W_CORNER_BOTTOM_LEFT) ; do { wGetEventWait (&event) ; } while (event.type!=WM_KEY || event.p.key.keycode!=W_KEY_ESCAPE) ; return(0); } The call wstartup takes care of routine preparation to interact with the Window Server (see the Window Server Reference manual for more details of all of these calls). The call gBorder draws a pleasant curved border around the edge of the screen. Vary the flags passed to gBorder for different types of curves. The call wSetBusyMsg displays the specified message flashing, at the nominated corner of the screen. In general, the message will continue to flash, without any assistance from the application, until such time as a call such as wcancelBusyMsg is made. 2-4 2 WRITING SOFTWARE FOR THE HC The call wcetEventwWait is a synchronous request to receive an event from the Window Server. These events include notification of coming into foreground or background, as well as keypresses and requests to redraw portions of the screen (these latter events are used by applications that explicitly handle window redraws - such applications do not use the wStartup function and instead use the lower level function). AS wGetEventWait is synchronous, it does not return until there is an event for the application to process. In this example, the application is uninterested in any events other than keypresses, and even then, only the ESC keypress is of interest. In order to build w_hello, simply type make w_hello when in the appropriate source directory (\sibosdk\demo). The Gauge application The Gauge application is altogether more sophisticated than w_hello: e the screen display contains text in various font styles. e the screen also contains a "growing scrollbar" or "petrol gauge" display item, whose content grows regularly, as a timer beats. e the speed at which the timer beats can be adjusted by keypresses from the user. e the user can also reset the gauge display at will. e the range of options open to the user is displayed on a range of "buttons", which momentarily highlight whenever they are selected. e in programming terms, a timer channel is created as a second event source. e the synchronous wGetEventWait call is replaced by the asynchronous version wGetEvent. The schematic form of main in gauge.c is as follows: GLDEF_C VOID main(VOID) { WS_EV event; WORD wactive; wStartup(); INITIALISE(); QueueTimer (); wactive=FALSE; FOREVER { if (wactive) wF lush () ; else { wGetEvent (&event) ; wactive=TRUE; } p_iowait (); if (event .type==E_FILE_PENDING) { PROCESS_TIMER_EVENT () ; QueueTimer (); continue; } wactive=FALSE; if (event .type==WM_KEY) { switch (event.p.key.keycode) { } 2-5 HC PROGRAMMING GUIDE The use of a little imagination will make it clear that this is the same basic architecture (albeit rearranged) as in the Events programs discussed in the General Programming Manual: e the variable wact ive is the active word for the Window Server event source e the status word for the Window Server event source is built into the ws_zv struct passed to the call wGetEvent: it is the event .type field e there is no test on the timer status word, timstat, since if the call to p_iowait has returned and event .type is still equal to E_FILE_PENDING, it can only be the timer which has an event to deliver (given that there are only two event sources in the application). The need to flush the Window Server buffer Note the special test on wact ive at the top of the event loop in main. If wactive is still TRUE, it means there is no need to call wGetEvent again (and in fact the application would be panicked if it did so). However, it is necessary, in this case, to call wFlush, to ensure that the Window Server function buffer is flushed out. Otherwise drawing calls could remain in this buffer all the time that the application is suspended, inside p_iowait. The point here is that, for efficiency (minimising IPC - InterProcess Communication - traffic between the application and the Window Server), many Window Server functions are not implemented immediately: rather, they are stored in a buffer which is only "flushed" every so often. See the Window Server Reference manual for full details. Another instance in the Gauge application where wFlush is called is in the routine Flash, in which a highlight is momentarily displayed over a "button" containing the choice the user has just selected: { P_EXTENT ext; gInvObloid(&ext) ; wFlush (); p_sleep (2); gInvObloid(&ext) ; } Other graphics calls in Gauge The contents of gauge.c can usefully be studied (eg use the SIBO Debugger while the program is running) for examples of the following graphics function calls: gPrintBoxText useful for "flicker free" drawing of text. gSetGc allows a change in the font or font style (and more besides) used to draw text. gClrRect clears or highlights a given rectangle. gFillPattern applies a pattern (here, a "grey" pattern) to an area. gTextWidth calculates the width of a string of text. gInvObloid allows special "rounded" or "obloid-shaped" inverse videoing. gBorderRect draws any of a variety of curves around the edge of a specified rectangle. A suite of line editor functions The application LinEd demonstrates the use of a suite of line editor functions: three line editors are created on the screen, each with text that the user can edit. The user chooses which entry to edit at any one time by using the UP and DOWN cursor keys. Other editing keys have the expected effects on the editors: ¢ typing printable characters enters these characters into the current string (with any existing highlighted selection in the string being deleted). e the editor beeps if it has already grown to its maximum size. e the editor scrolls horizontally if there are more characters to display than can fit in the width allocated to it on the screen. 2-6 2 WRITING SOFTWARE FOR THE HC e the DEL key deletes the character to the left of the cursor, whereas SHIFT+DEL deletes the character to the right of the cursor, PSION+DEL deletes to the end of the line. @ PSION+LEFT and PSION+RIGHT "home" and "end" the cursor, respectively, LEFT and RIGHT just move the cursor one position. The suite of "lined" (line editor) functions should be independently useful, either in their present form, or modified for particular purposes (the lined functions are as they stand fairly general). From a broader perspective, the lined functions demonstrate the creation of a user interface for applications on the HC. The code in lined.c divides into two parts: the implementation of the lined functions, and the testing of these functions. The main routine of the test program is worth considering in full: GLDEF_C VOID main(VOID) { LINED *ed[3]; INT which; WS_EV event; INT keycode; wStartup(); gBorder (W_BORD_CORNER_4) ; ed[0]=CreateLined(10, "One", TRUE) ; ed[1]=CreateLined (30, "Two", FALSE) ; ed[2]=CreateLined (50, "Three", FALSE) ; which=0; FOREVER { do { wGetEventWait (&event) ; } while (event.type!=WM_KEY) ; keycode=event.p.key.keycodeé& (~W_SPECIAL_KEY) ; switch (keycode) { case W_KEY_ESCAPE: if (event.p.key.modifiers==W_PSION_MODIFIER) p_exit (0); case W_KEY_UP: if (which) { le_emphasise (ed[which--],FALSE) ; le_emphasise (ed[which], TRUE) ; } break; case W_KEY_DOWN: if (which<2) { le_emphasise (ed[which++],FALSE) ; le_emphasise (ed[which], TRUE) ; } break; default: le_key (ed[which], keycode, event.p.key.modifiers) ; } } The array of three pointers ea[3] is used to hold the "handles" of the three lined objects created. This creation is done inside the call createLinea (further discussed below). At any one time, only one of these three editors is "active" - displaying a flashing cursor and receiving editing keys from the user. The application uses the variable which to keep track of the current active editor. On receipt of an UP or DOWN key, the application changes its record of which editor is active. At the same time, the editors themselves have to be informed of this change - so that they can adjust their appearance. This is the role of the calls to 1e_emphasise. All other keys (apart from PSION+ESC, which exits the application) are passed straight through to the current editor, using the call 1e_key. 2-7 HC PROGRAMMING GUIDE Full specification of the lined functions The routine 1e_init creates and initialises a lined object, according to the data in an IN_LINED struct passed. This creation involves two separate allocator calls - one for the control block of the editor itself, and one for the buffer to hold the string of text to be edited. Note that either of these calls can fail - in which case the failure is reported back to the caller. The test application in Jined.c ignores this possibility, under the rationale that the minimum heap of the application guarantees that these calls, made during program initialisation, will always succeed. The call either returns NULL, in the case of an alloc failure, or the handle to be used to identify this particular editor in all subsequent 1e_xxx calls. The meanings of the fields in the interface struct IN_LINED (defined in /ined.h) are as follows: maxchars the maximum length of text that can be edited. winid the id of the window in which the editor is to appear. xoff the x-offset from the origin of the window to the top left of the editor (in pixels). yofft the y-offset from the origin of the window to the top left of the editor (in pixels). width the width of the editor (in pixels). height the height of the editor (in pixels). asc the distance (in pixels) between the top of the editor and the base line of the text edited. font the identifier of the font used to display the text. style the style of the font used to display the text. autoselect TRUE to automatically select the entirety of any text set into the editor by the calling program, FALSE to leave such text un-selected. Note how these fields are set up in the routine createLined: LOCAL_C LINED *CreateLined(INT yoff,TEXT *msg, INT emph) { IN_LINED init; LINED *ed; init.maxchars=20; init.winid=wMainWid; init.xoff=10; init.yoff=yoff; init.width=80; init.height=10; init.asc=8; init. font=WS_FONT_BASE+4; init.style=0; init.autoselect=TRUE; ed=le_init (&init); le_set_text (ed, p_slen(msg) ,msg) ; le_emphasise (ed, emph) ; le_visible (ed, TRUE) ; return (ed) ; } The static wMainwWid is one that is set up by the call wstartup. See the Window Server Reference manual. The initial text of the editor is set in by a call 1e_set_text made after the call to 1e_init, but before the call to le_visible which causes the editor to actually be drawn. Also in between the 1e_init and le_visible calls is a call to 1le_emphasise to specify whether the editor should be displaying a flashing cursor (and also whether any selected region should be visibly highlighted). Another call that could be made between 1e_init and le_visible is le_set_cwidth, to change the width of the flashing cursor from its default (which is two pixels wide). 2-8 2 WRITING SOFTWARE FOR THE HC As noted above, the way the application sets text into a lined object is with the call 1e_set_text. In this implementation, the application is required to specify the length of the string as a parameter to le_set_text - le there is no requirement to pass the string in zero-terminated form. On the other hand, the editor itself maintains the string, as it is edited, in zero terminated form - which may be convenient for the application. The way the application can "sense" the contents of the string, as edited by the user, is simply to read this string out from the data maintained by the lined object. For this purpose, the form of the L1NeEp struct needs to be known. This struct is defined in lined.h. Needless to say, most parts of the data in this struct are strictly read-only. If an application writes directly into this data, random problems can ensue later. If a lined object is no longer needed, all the memory it uses can be freed by calling 1e_dest roy. Be sure to have an independent copy of the string edited, before making this call. Finally, the function 1e_visible, as well as initially making the editor visible, can also be used at some later stage to "hide" the editor again, if desired. General comments Device drivers for the HC Note that the i/o Devices Reference manual gives details of how to program many of the peripherals that can be attached to an HC: a parallel port. a serial port (including xmodem and ymodem file transfer). a magnetic card reader. a bar code reader. a modem. The chapter The HC in the Cradle, later in this manual, gives details of the operation of the HC when located in a cradle. Writing a customised shell process The System startup section of the Introduction chapter of the Window Server Reference manual gives two examples of possible small alternative shell programs. The source for one of these, /kshell.c, may be found in \sibosdk\demo. As well as presenting the source, this section of the SDK raises various issues to do with replacing the built-in shell program with a customised one. In case it is desired to create a shell process with functionality intermediate between /kshell and corpshil (which is the Command Shell), see the documentation, later in this manual, of each keyword supported by the Command Shell, for a reference to the C functions used to implement that keyword. Developing applications on restricted-keyboard HCs Developers writing for HCs with restricted keyboards lacking a full set of alphabetic keys face the problem that many commands that might ordinarily be typed into an HC during the course of program development - for example, file or SSD management commands in the HC Command Shell - simply cannot be typed into the HC, on account of the required alphabetic keys not being present on the keyboard. In practice, preliminary development would probably be done using a different HC, with a fuller complement of keys. The program being developed would only be transferred to the restricted-keyboard HC at a later stage of development. However, the problem recurs at this later stage. The comprehensive solution to this problem involves one of the fundamental principles of the HC - its interconnectability with other computers. Briefly, rather than the HC being controlled from its own keyboard, it can be controlled from a remote keyboard, say that of a PC. The commands are transmitted to the HC via one or other form of serial connection. See the chapter HC Command Sheil for more details of this mechanism. 2-9 HC PROGRAMMING GUIDE 2-10 CHAPTER 3 HC COMMAND SHELL Overview The HC Command Shell provides a MS-DOS like utility for functions that can be executed from a command line. The range of functionality covered includes file and SSD management, program management, information requests, and HC configuration. Commands can be entered by typing at the HC command line in response to a $ prompt. Alternatively, commands can be entered remotely, by typing at the terminal of a PC connected to the HC. The HC will run batch files consisting of a sequence of commands. Batch files can be run in either of the above modes. Batch file processing Epoc batch files are plain text files consisting of a series of commands. Each command has a line to itself. By default batch files have extension . btf: To invoke a batch file with name backup.btf, type @backup at the Command Shell s prompt. If necessary specify the full path of the batch file. Thus @loc::b:\batch\backup or @rem::c:\hc\devp\restore.bat would both invoke batch files. In the first case the file is assumed to have a .btf extension. In the second case the file extension is specified to be .bat. Batch files can also call other batch files, and so on, up to eight levels deep. Batch files are executed synchronously, i.e. no additional commands can be typed into a Command Shell until any batch files it is executing have completed. Whilst batch files significantly enhance the utility of the HC Command Shell they do have some notable limitations: e they cannot have parameters passed to them. e they cannot contain conditional statements, such as if ... goto ... These limitations can be got round by replacing the batch file with a program written in Opl, or in another high level language such as C. Launching programs The Command Shell can be used to launch both batch files and programs (either Epoc executables or OPL programs). Epoc executables and OPL programs are run by simply typing their name without any additional prefix (except possibly for an « - see below). 3-1 HC PROGRAMMING GUIDE When the following line is entered at the Command Shell dojob the HC will attempt to locate the corresponding command or file. The HC will execute this command or file when and if it is found. The search is carried out as follows: the HC checks that there is no internal command with the name dojob the HC looks for a file dojob.opo in the current directory e the HC looks for a file dojob.opo on a:, b:, and m: (in the order given) e the HC looks for a file dojob.img, first in the current directory, then (as above) on drives a-, b:, and m., and then in rom:: e the HC looks along the same search path for a file dojob.app. The search terminates once the command or file is found. Note that a file dojob.opo will be found in preference to a file dojob.img. To ensure that a file dojob.img is run, enter the extension explicitly: dojob.img Programs are assumed to be Epoc executables unless they have the extension .opo, in which case they are assumed to be translated Op! programs. Additional parameters can be passed to these programs. For example, dojob b: Synchronous programs and asynchronous programs In contrast to batch files, which are always run synchronously (see above), programs can be run either synchronously or asynchronously thus exploiting the multi-tasking capabilities of the HC. By default, programs are launched asynchronously. This means that while the program is executing, the user can task back to the Command Shell and continue to issue other commands. When the program is started, it will by default (assuming it has a user interface) take over the foreground screen. To access the Command Shell, or indeed any other tasks that may be running on the HC at the time, press TASK as many times as is required. Every time TASK is pressed, a different program cycles into foreground. Note that there is no need to quit the foreground program in order to start another - start a new program by pressing the TASK key until you get into the Command Shell, then type the name of the program at the command line. However, users should avoid starting up new programs unnecessarily - since each additional program reduces the memory available for the programs already running. To run a program synchronously, prefix the program name with an «. Note however that the command offenable 0 should be issued before synchronously executing any lengthy program - otherwise it will be impossible for the user to switch the HC off until the program has completed. Terminating programs Many programs include a facility that allows user termination. For example many programs contain an Exit menu command. When required the user can kill a program from the Command Shell, using either the terminate or kill commands. As explained in the alphabetical listing (see below), terminate should be used in preference to kill whenever possible. A program run synchronously can not be terminated by tasking to the Command Shell that launched it - since that Command Shell is inaccessible until the program terminates. In extreme circumstances it may be necessary to reset the HC. When a program launched from a Command Shell terminates, either normally or abnormally, the Shell reports this fact to the user. 3-2 3 HC COMMAND SHELL The command line editor Up to eight previous commands can be reviewed by means of the UP and DOWN cursor keys at the command line. Any previous command displayed in this way can be edited before being issued again. To clear the command line at any time, press ESC. As might be expected, each individual command is entered to the HC by pressing ENTER after typing its name. In most cases, the name can be abbreviated, as indicated in the alphabetical listing below. Pausing the screen display Some commands (such as iproc and iseg) automatically pause when a screenful of information has been displayed. Other commands (such as dir) must be entered with a /p flag to obtain the same effect. In either case, pressing any key will resume the display (though the ESC key sometimes terminates the command listing). At all times, the display of the Command Shell can be paused, independently, by means of the PSION+LEFT key combination (or by SHIFT+LEFT on restricted keyboards (this feature is shared by all console programs). Again pressing any key will resume the display. Additional copies of the Command Shell The Command Shell can be run from the command line just like any other program. The first and subsequent copies of the Command Shell differ only in that, by default, subsequent copies terminate as soon as they have processed the command lines passed to them. For example typing sys$sh1l ver runs a copy of the Command Shell with the command line argument ver. The effect is the same as simply typing ver on its own except that the new copy of the Shell terminates after the ver command completes. The display then reverts to that of the previous Command Shell. To force a copy of the Command Shell to pause before terminating, type /p immediately after sys$sh11. Thus sys$shll /p ver causes the display to pause waiting for any keypress, after completing listing the version information. Exceptionally, if there is little available memory on the HC (for example, if there are many files on m:) additional copies of the Command Shell may fail to perform fully as expected. Sending commands from a remote PC The utility of running second copies of the Command Shell is most apparent when used in conjunction with MCLink. MCLink allows programs on the remote computer (in this case, the HC) to be invoked with the MCLink run command. For example, typing run sys$shll /p del *.bak at the MCLink command line is essentially equivalent to typing del *.bak at the command line of the HC. Operators may find typing at the PC to be more convenient than typing on the naturally more restricted keyboard of the HC. In cases where the HC has only a numeric keyboard, commands must be entered using a mechanism such as MCLink running on some remote computer. The following alias may prove especially useful: typing | at the MCLink command line is shorthand for typing run sys$shll Thus typing ! /p del *.bak at the MCLink command line may be a yet more convenient way of issuing the HC with the command del *.bak 3-3 HC PROGRAMMING GUIDE Often even typing these few characters is undesirable (it is impossible in the case of restricted keyboard HCs) and so a batch file is used instead. A batch file autoexec.btf is placed in the root directory of an SSD. This batch file is executed whenever the HC is reset - if the file contains the command link, the Link software will automatically be started every time the HC is reset. Another (more advanced) possibility is to place an alternative (custom) shell on an SSD, before resetting the HC. More on running programs remotely Even if an alternative (custom) shell is running on an HC, the Command Shell can in many cases still be invoked by means of typing (eg) ! /p ver at the command line of MCLink. This mechanism may be found useful in cases where it is briefly required to access the functionality of the Command Shell, even though, ordinarily, a custom shell is run in place of the Command Shell. Occasionally this mechanism will fail to work - for reasons explained below - with a second copy of the custom shell being run instead. The MCLink run command proceeds as follows: e first, an extension .img is added to the program name supplied and if no extension was explicitly supplied e the Link software starts looking, on the remote computer, for a program with this name; if at any stage a program with this name is found, an attempt is made to execute it; if this attempt fails, the search continues e the first place searched is the current path of the Link software on the remote computer (see below for an explanation of the concept of current path) e the search continues, if required, in the ROM of the remote computer e finally, if required, the search continues on all the root directories of the remote computer, in alphabetical order. Accordingly, if the current path of the Link software on the HC contains a custom copy of sys$shll.img, this copy will be launched by an MCLink ! command; otherwise, it will be the Command Shell (from the HC ROM). In practice, the only way for the current path of Link software on an HC to differ from m-\ is for a set command to be issued before the Link software is started. There is one further complication when attempting to simultaneously run two different programs with the same name. Ordinarily, Epoc will refuse to allow the second program to run and will generate a "File already exists" error message. The only exception is if the second program is in ROM. This explains why the Command Shell can be started when a custom shell is already running, whereas a custom shell cannot be started with the Command Shell still running (try it and see). Auto-terminating and non-auto-terminating Command Shells A Command Shell will only auto-terminate if invoked with a command line. Whether an instance of the Command Shell is the first or an additional copy is irrelevant. To run an additional copy of the Command Shell that does not auto-terminate after processing its command line (either straightaway, or after pausing to receive a keypress), just type sys$sh11 by itself, without any additional parameters (any "Capture failed - File already exists" error message can in this case be safely ignored). Files and directories File In Use error messages On the HC an open file can only be accessed by the application that opened it. An attempt by another application to modify the file will lead to a File In Use error message. As a consequence file commands issued from the Command Shell will fail when asked to access an already open file. For example an attempt to copy an open file will generate a File In Use message. 3-4 3 HC COMMAND SHELL Default path and current directory In Epoc there is one current path for each running process (in Epoc it is preferable to refer to the current path rather than the current directory as this also includes the drive and the filing system). In contrast MS-DOS logs a current directory for each drive and thus has as many current directories as drivers. The current path of a Command Shell can be altered using the cd command. For example cd b:\play would change the current path to »:\piay. Note that this could have a quite different effect in MS-DOS. In MS-DOS change the current directory to a:\work\ then type cd b:\play\ followed by a dir command. The dir command will list the files in a:\work\ and not those in b.\play\. Changing the current path for one application does not alter the current path for any other application. This is in contrast to and an improvement on MS-DOS. In this case the currently logged directories in the command shell can be annoyingly altered by running (synchronously!) another process. By the time the second process has terminated the MS-DOS command shell may have been logged to a different drive and a different directory. The HC Command Shell also supports the command set to alter the so-called default path which affects all applications subsequently launched. The set command has no effect on the current path of the present application but provides the initial current path for all future launched applications (regardless of where these applications are launched from). Thus the sequence of commands cd m: set b: sysS$shll dir cd a: dir exit dir will bring about the following sequence of directory listings: e first the second copy of the Command Shell lists the contents of b:\ since its current path was set (on initialisation) to b; with the set command.(in the parent Command Shell) e next, after changing the current path of the second Shell to a.\, the second dir command lists the contents of a:\ e finally, once the second copy of the Shell has been exited, the last dir command lists the contents of m.\ - since the current path of the parent Shell has been affected by neither the set command (as that does not alter the current path) nor the cd command (as that altered the current path of a different process). Note that any changes to the path of a Command Shell inside a batch file will continue to have effect after the termination of the batch file, since no new process is run up, just by virtue of a batch file being executed. Specifying file names as command parameters It is not always necessary to supply the full specification for a filename when passing it as an argument to a Shell command. The missing parts (if any) are filled in from the current path. Thus if the current path is m:\img\, the command att job.img -r operates on the file with full path name m:\img\job.img and the command att b:\backup\job. img operates, naturally enough, on the file b:\backup\job.img - regardless of whether the current path is on m-, b:, or whatever. Beware that att b:job.img is equivalent to att b:\img\job.img and not att b:\job.img (the first and last forms differ only in the presence or not of a back-slash immediately after the colon). The reason why these two forms are interpreted differently is that the filename b-job.img is interpreted as having three parts: e =adrive (b:) e a basic name (job) e an extension (.img). 3-5 HC PROGRAMMING GUIDE As the path is not explicitly specified, the path specified in the current path of the application will be assumed. If the (incorrectly specified) file is not found the command will fail with the error message "Directory does not exist". To specify a file job.img on the root directory of b:, type b:\job. img, including the crucial \ character. More details on filename specifications Filenames are assumed to have five parts: e =afiling system (eg loc:: or rem::) e = adrive (eg b:) e a path (eg \ or \accounts\jan\) e a basic name (eg job) e¢ an extension (eg .img). The current path of an application contains the first three components. It does not contain the last two. The filing system will always be assumed to be that specified in the current path unless an alternative is explicitly supplied. Note that various Shell commands may unexpectedly fail to work if the filing system specified in the current path is set to rem::, and the remote link connection is subsequently broken. Specifying paths as command parameters When using a command such as cd it is often more convenient to omit one or more components of the path as any missing components will be filled in from the current path. Thus with a current path of m.\img\ the command ca files would be equivalent to cd m:\img\files and the command mad tools would be equivalent to md m:\img\tools. Note that it can sometimes be an error to supply a trailing back-slash. Whilst mad m:\img\tools\ is acceptable, md tools\ is not. The reason is that the trailing back-slash indicates that a path component follows - the ma command does not expect a path component to follow. The requirements of generality The user might consider the syntax of HC Command Shell commands to be more limiting than the MS- DOS equivalent - the syntax of commands such as md and rd on the HC is not the same as that of the ma and rd commands in MS-DOS although there are considerable similarities. The extra limitations stem from a central design feature of the Epoc operating system - under Epoc an application can directly access files that are stored on a remote computer whose filing system may or may not be MS-DOS. Alternative remote filing systems that need to be borne in mind include Unix, Vax VMS, and the Apple Macintosh operating system. Thus if the HC is connected to an Apple Macintosh computer, the following could be entered at the command line: cd rem: :hd40:hcdevp: stock Accordingly, the HC Command Shell does not simply approach filenames and path specifications in terms of questions of back-slashes (were the Shell to insert a back-slash at the end of the above command, "on behalf of the user", this would, most decidedly, not be what the user intended). Instead, the approach is much more general, in terms of the five part breakdown of filename specifications discussed two sections previously. Similarly, the HC provides no support for the syntax of "double dot" (for the parent directory) and "single dot" (for the current directory). Although this extra discipline has its occasional drawbacks, the advantages that it brings with it are an important part of the vital inter-connectable feature of the HC. 3 HC COMMAND SHELL Alphabetical listing Notation This list of commands uses the following syntax: COM[MAND] supplied-parameter [optional-parameter] Items shown in square brackets ([]) are optional. To include optional information, type only the information within the brackets. Do not type the square brackets themselves. Legal shortened versions of commands may be inferred from the syntax given. Thus in the above (generalised) example, com would be an acceptable shortened form of commanp. Any intermediate form between com and command would also be acceptable - eg comm (but not comd, needless to say). Commands can be typed in any combination of lower and upper case. For example, except where clearly stated to the contrary below, pairs of command such as wnot on and wnot on are completely equivalent. Commands must be separated from their options by inserting a space character. Default values may be assumed if some options are not supplied. Default values of particular commands are given in the individual command descriptions which follow. Note: the following list actually contains two entries that are not really commands of the Shell, in the strict sense, but are just the names of programs in the rom: 1ink and bat chk. However, this distinction may seem irrelevant to the user, and so, for convenience, these commands are listed too. How commands are implemented In many cases, the description of a command below gives the name of some of the key C functions involved in the implementation of that command. This is provided partly for interest, partly as an additional reference source (so that the corresponding section of the Plib Reference or Window Server Reference manuals can be consulted), and partly as a guide for people wishing to write an alternative shell (or shell-like) program. Command ATTRIBUTE _ Setor clear file attributes (ATTRIBUTE) ATT[RIBUTE] filename [(+/-)h] [(+/-)s] [(+#/-)m] [(+/-)r] Sets or resets the hidden (nh), system (s), modified (m) and/or read-only (x) attributes of a file. For example, att list.dat -m +s clears the modified attribute and sets the system attribute of list.dat, without altering its hidden or read-only attributes. For each of h, s, m, and r, a prefix of - clears the corresponding attribute, and a prefix of + sets it. The four attributes can be specified in any order, and any combination of the four bits can be set or cleared at once. Omitting all four is pointless: nothing will happen. The attribute command does not accept a wild card specification. This command is implemented via the C function p_sfstat. Note that the air command includes the attributes of files as part of its display. Command AUTO Set time to auto-switch-off (AUTO) AUT[O] seconds Sets the time for auto-switch-off. The auto-switch-off time is set to seconds. If seconds is -1, auto-switch-off is disabled. The maximum value for seconds is 32767, and the minimum non-zero value is 15. This command is implemented via the C function p_setauto. HC PROGRAMMING GUIDE Command BACKLIGHT Set backlight time-out (BACKLIGHT) BACK[LIGHT] [time] Sets the backlight auto-time-out to time, or if time is omitted, displays the current setting (in hexadecimal). The value of time is in ticks, ie 1/32 of a second. If time is zero, the backlight will remain on for as long as the HC is switched on. Passing time as negative has the effect of disabling the BACKLIGHT key. In that case, the backlight can only be switched on under software control. This command is implemented via the C functions p_backlight, p_getbacklight, and p_setbacklight. Command BATCHK Start battery check program (BATCHK) BATCHK interval Starts the program rom::batchk (if found), which monitors the voltages of the main and backup batteries. The value of interval gives the time period, in tenths of a second, between the time when checks are made. If either battery is found to be low when a check is made, a Notifier is displayed. The batchk program also captures the INFO key so that, whenever this key is pressed, the user is presented with information on the current voltages of the batteries. At the same time, a Notifier is displayed if either battery is low. Passing interval as 0 has the effect that a check on the battery voltages is performed only when INFO is pressed; no timer operates in this case. If interval is omitted, it defaults to 3000 (5 minutes). Any value of interval less than 100 has the same effect as passing 0. A copy of batchk is automatically run when the Command Shell starts. The Command Shell starts batchk with a value of interval equal to zero. Attempting to run a second copy of batchk without terminating the first will result in an error message and then a notification of abnormal program termination (the second copy of batchk). In order to change the value of interval that is in operation, to ten minutes (say), the following has to be entered: term batchk batchk 6000 See the lowbat command for an independent method of checking the battery voltages. The core functionality of the batchk program is provided by the C calls p_supply and p_wsupply. Applications in which it is critical that battery power does not drop too low during some activity should make their own calls to these functions when needed. Command BATTERY Specify battery type (BATTERY) BAT[TERY] type Specifies which type of main battery is installed. This information may be used by other software on the HC, affecting (eg) when low battery warnings are issued. Allowed values of type include: 1 alkaline batteries 2 600 mAh Nickel Cadmium batteries 3 1000 mAh Nickel Cadmium batteries 4 500 mAh Nickel Cadmium batteries. This command is implemented via the C function p_setbat. 3-8 3 HC COMMAND SHELL Command CD Change directory (CD) CD [path] Changes to a different path, or (if path is omitted) displays the current path. For example, to change the current directory from \work\product\ to \work\admin\, type cd \work\admin\ To move to a directory below the current one, only the path from the current directory needs to be entered. So to change from \work\admin\ to \work\admin\forms\, the following command could be used: cd forms\ The trailing back-slash in the above commands can be omitted. Thus cd forms instead of cd forms\. There is no support for a command such as ca .. (to move to the parent directory). Type cd b: (or ca b:\) to change to the root directory of b:. This command is implemented via the C function p_setpth (amongst others). Command CONFIG Set language file (CONFIG) CON[FIG] filename Changes the language data file to that specified. If £i1ename is omitted, the effect is to revert to the file sys$ctry.cfo. If the extension is omitted, it is assumed to be .cfo. The file given must be in the ROM of the HC. Unless a specially customised version of the ROM has been made, this in practice limits the use of this command to config custom$.dat where the file custom$.dat has been specially prepared by means of the tool romwrite. The effect of specifying a file that has an unsuitable form is drastic: almost certainly, the HC will require a hard reset to recover. This command is implemented via the C function p_setconfig (amongst others). Command COPY Copy file(s) (COPY) COP[Y] source_filespec target_filespec Copies one or more files, possibly changing their names in the process. Any part of the target filename that is not specified (for example, the extension) and which cannot be filled in from corresponding parts in the current path is taken from the corresponding part of the first pathname. The wildcards « and ? can be used to copy multiple files. For example, copy fred.* a:\jim.* copies all files such as fred.btf from the current directory into the root of a.\, renaming them (eg to jim.btf) in the process. As a possibly surprising example, if the current path is m-:\, the command copy a:\file.lis file.old has the effect of copying the named file to m.\file.old. As files are copied, the names of the files created are listed on the screen. A file cannot be copied onto itself. If an attempt is made to do this, the copy command quits, and an error message such as the following is displayed: Copy failed - file or device in use This command is implemented via object-oriented techniques using the fman object in Olib.dyl. 3-9 HC PROGRAMMING GUIDE Command D Brief directory listing (D) D [/p] [filespec] Lists specified filenames in a directory, without any additional information except for the total size and the total number of bytes free on the current device. Typing d by itself lists all filenames in the current drive and directory. Typing a and a path, such as a:\, lists all entries in the specified directory. If a filename without an extension is included (invoices, for example), all files named invoices in the specified directory will be listed, whatever their extension. The wildcards « and ? can be used in the file specification. The /p flag causes the display to pause at the end of each screen. When the display is paused, it can be resumed by pressing any key. However, if ESC is pressed, the directory listing is terminated. This command is implemented via the C functions p_open(P_FDIR), p_dinfo, and p_iow(P_FREAD). Use the dir command for a fuller listing of the details of files. Command DATE Display date and time (DATE) DAT[E] Displays the current date and time. This command is implemented via the C function p_date. Use the setdat command to change the date and/or time. Command DELETE Delete file(s) (DELETE) DEL[ETE] filespec Deletes the specified file or files. To delete more than one file at a time, the wildcards * and/or ? can be used. Alternatively, the following deletes all files in the directory \temp\: del \temp\ As files are deleted, the names of the files deleted are listed on the screen. This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which result, in the end, in calls to the C function p_delete. See also the command ra, which, in contrast to del, can delete directories. Command DEVICE List devices (DEVICE) DEV[ICE] [filespec] Lists all devices ("drives") in the filing system specified by f£ilespec. The only relevant part of filespec is the filing system (loc::, rem::, or whatever). For example, dev rem:: lists the devices in rem:: - assuming a remote connection is established. Typically, the command dev just results in the following listing: List of file devices for LOC:: A: - OK B: -— OK M: - OK In practice, the only time a device will be reported as other than "ox" will be if the connection to a remote computer is broken midway through listing the devices of rem::. This command is implemented via the C functions p_open (P_FDEVICE) and p_iow(P_FREAD). 3 HC COMMAND SHELL Command DIR Full directory listing (DIR) DIR [/p] [filespec] Lists all the specified files in a directory, together with their sizes, the time and date of their last modification, and their attributes. The wildcards * and ? can be used in the file specification. The /p flag causes the display to pause at the end of each screen. When the display is paused, it can be resumed by pressing any key. However, if ESC is pressed, the directory listing is terminated. This command is implemented via the C functions p_open(P_FDIR), p_dinfo, p_iow(P_FREAD), and p_finfo. Use the a command for a briefer listing of the details of files. Command ENV Display or set environment variable (ENV) ENV [var[=[value] ]] Displays or sets the value of environment variables. With no parameters, the values of all current environment variables are displayed. If var is given but without any trailing equals sign (=), the values of all environment variables matching the specification in var are listed. If the equals sign (=) is given too, the environment variable var is set to value. But if the equals sign is given whilst value is omitted, the environment variable var is deleted. For example: env $wWs* displays the values of all environment variables whose names start with sws env last=34 sets the value of 1ast to the string 34 env last= deletes the environment variable 1ast. Values are displayed inside square brackets. The list pauses when the screen is full. Note that environment names and values are both case dependent. Thus the environment variables group and croup would be distinct. Indeed, environment names and (more likely) environment values can even be binary. Non-printable byte values are displayed as (eg) or . There is no mechanism for setting binary values from the Command Shell. This command is implemented via the C functions p_findenviron, p_delenv, and p_setenv. Command EXIT Exit level (EXIT) EXI[T] Exits the Command Shell. May be used to terminate second copies of the Command Shell that are no longer required. If the exit command is typed into the first copy of the Command Shell, the HC will automatically re- launch a shell process, as explained in the chapter Introduction to the HC. If the exit command is found in a batch file, all that happens is that the batch file is terminated, and control passes back to the previous level of batch file (or to the command line). The command is implemented (when not in a batch file) by the C function p_exit. Command FORMAT Format device (FORMAT) FOR[MAT] [device:] [volname] Formats Ram and Flash SSDs (or the internal disc m:). HC PROGRAMMING GUIDE The command detects the type of SSD and places the appropriate format information onto the disk. This information differs for Flash and Ram SSDs. The volume name volname is optional. For example, format a:new will format the a: device, giving the volume name new. If device: is omitted, the internal memory is formatted. Note carefully that no warning is given before the formatting takes place. So accidentally typing (eg) for b could be disastrous: e since no colon is typed, b is interpreted as the volume name e since no device name is specified, formatting defaults to m: e accordingly, all data on m: is lost in a trice (with the volume name of m: being set to b). The mere fact that there are read-only files on an SSD will not prevent it from being formatted. However, if an SSD has the write-protection switch set, it will not be possible to format it. Another reason for format being disallowed for a disk would be if there are any open files on it. In this case, the format request will fail with the error message "File or device in use". This command is implemented via the C functions p_open (P_FFORMAT) and p_read. Command FREE Display free memory (FREE) FRE [E] Displays the amount of free RAM in Kbytes. Note that this in general exceeds the amount of bytes free in m:, as reported by a dir or d command. The discrepancy is because some parts of internal memory are reserved for code and data segments; not all of it can be allocated to the contents of m:. This command is implemented via the C function p_sgfree. Command KILL Kill a process (KILL) KIL[L] procname Kills the first process found matching the specification in procname. To kill a specified instance of a number of running tasks, all with the same name, the exact process name must be found out and used. Eg kill job.$09 Or kill job.$14. Use the 1proc command to give the full process names of all current processes. Note that ki11 should only be used as a last resort, as it does not allow the process to tidy up before exiting - this is a problem with the Link application which starts a number of sub-processes. To shut down a process, terminate should normally be used in preference to kill. This command is implemented via the C function p_pkill. Command LDEV List device drivers (LDEV) LDE[V] [device_spec] Lists all specified device drivers. The list includes all ROM-resident device drivers, as well as external ones that are currently loaded. If device_spec is omitted, it defaults to *.*. For each device driver listed, the label /dd or pdd is given - the former for logical device drivers (which are hardware-independent), the latter for physical device drivers (which are hardware dependent). 3-12 3 HC COMMAND SHELL For example, entering 1dev con displays List of devices:con LDD - CON (units=-1) The value given for units is the number of channels a logical device driver can support. A value of -1 means that an unlimited number of channels can be opened. As another example, entering 1dev fsy displays List of devices:fsy PDD - FSY.REM PDD — FSY.LOC PDD - FSY.ROM listing the three ROM-resident filing system device (fsy) drivers - for rem::, loc::, and rom::. This command is implemented via the C functions p_devfnd and p_devqu. Command LINK Start Link program (LINK) LINK [-b] [-p] [filename] Starts the Link communication software on the HC. If filename is specified, it is assumed to specify a .trm file, and in that case, there should be no other parameters on the command line. The extension .trm is supplied for filename if required. If the command line is empty, the Link software searches as follows for a file mclink.trm to configure it: e first, in the current path of the Link software e next, in the HC ROM (where it will indeed find a file mclink.trm). The format and creation of .trm files is discussed in the Additional System Information manual. Possible values of baud range from 19200 and 9600 all the way down to 110, 75, and 50, with all common baud rates in between being supported. In the absence of a command line and if no external mclink.trm file is found, baud defaults to 9600. If the port or serial_device 1s specified but not baud, baud defaults to 19200. The only time it is necessary to specify port is if there are serial expansion devices in both the top and the bottom of the HC. In this case, the parameter -p1 means to use the top port, and -p2 means to use the bottom port. Otherwise, the Link software simply uses whichever port is available. (Other parameters are also possible but are omitted from the present description. See the chapter Mclink, Mcprint, and Slink in the Additional System Information manual.) Just typing 1ink should suffice in the majority of cases. To terminate the Link software at some later date, type term link. To discover whether or not Link software is running, type lproc link. If the 1ink command is issued while Link is already running, a second copy of Link will be launched briefly, but will quickly exit with the error number -32 (or 224), meaning that a process link. * already exists. No harm will ensue as a result. See the section Connecting to other computers in Introduction to the HC, for more details. Command LOWBAT Configure low battery warnings (LOWBAT) LOW[BAT] state If state is on, the HC will check, each time the HC is switched on, for either of the batteries being low. On detecting a low battery, the HC will issue a warning in the form of an information message in the bottom right hand corner of the screen. 3-13 HC PROGRAMMING GUIDE If state is orr, this behaviour will not take place. (This is the default.) This command is implemented via the C function wsystem. See also bat chk for an independent method of periodically checking the battery voltages. Command LPROC List processes (LPROC) LPR[OC] [process_spec] Lists information about all specified processes. The information listed is: e the full process name (in the form batchk.$07) e the size, in bytes, of the process data segment (given in hexadecimal) e the current state of the process. If process_spec is omitted, it defaults to *.*. Possible values of the state of the process are: CURRENT the process is currently receiving cpu READY the process has some events ready to process, as soon as cpu is given to the process by the multi-tasking scheduler DELTA the process is "sleeping" (eg as a result of calling the C function p_sleep) sus the process has been suspended SEM the process is waiting for some event to happen. Additionally, the text wsusp will be displayed if the process is waiting to be suspended. For example, entering lproc sys$shll may produce the display List of processes:sys$shll SYSSSHLL.$05 3DA0 SEM SYSSSHLL.$11 3DA0 CURRENT One common use of the lproc command is to check whether Link software is currently running: 1proc link. This command is implemented via the C functions p_pfind, p_getosd, and p_sgsize. Command LSEG List segments (LSEG) LSE[G] [process_spec] Lists all memory segments currently in use by the specified process(es). If process_spec is omitted, it defaults to *.*. The information listed about each memory segment is: e its size in paragraphs (one paragraph is sixteen bytes) ¢ its segment address e its access count. Values are displayed in hexadecimal. At the end the display, the total size in paragraphs of all the free segments is given (this gives the same value, when converted into Kbytes, as free). This command is implemented via the C functions p_sgfind, p_getosd, and p_sgfree. 3-14 3 HC COMMAND SHELL CommandMASTER Display time/date of mastering (MASTER) MAS [TER] Displays the time and date when the ROM was mastered. The command is implemented by the C function p_finfo, passing as a parameter a file known to be in the ROM (rom: :sys$shll.img). Command MD Make directory (MD) MD path Makes a directory. When a directory is created, it will appear in the current directory, unless a different path is explicitly specified. It is possible to omit the trailing back-slash from the path specification. The following commands both create a directory named \work\ in the root directory of the current drive: md \work\ md \work This command is implemented via the C function p_mkdir. Command NOTIFY Control whether the Notifier appears (NOTIFY) NOT[IFY] state Controls whether the Notifier ever appears as a result of a file operation carried out by the Command Shell. If state is on (this is the default), and a file operation unexpectedly fails to find an SSD that was present earlier, a Notifier will be presented giving the user the opportunity to replace the SSD, instead of just having the file operation fail. If state is orF, no such Notifier will be displayed. The notify command in the Shell has no effect on whether Notifiers are ever displayed by other programs. This command is implemented via the C functions p_setnotify and p_getnotify. Command OFFENABLE _ Enable off-key handling (OFFENABLE) OFFE[NABLE] value If value is 0, the Command Shell gives up its capture of the OFF key, thereby allowing other applications to capture this key to do their own processing of it. If value is any non-zero number, the Command Shell attempts to capture the OFF key again. This command is implemented via the C functions wcaptureKey and wcancelCapturekey. Note that there is no special need to have any application capture this key, since by default, the HC simply switches itself off when this keypress is received. The behaviour of the Command Shell in response to the OFF key adds nothing to this. Indeed, it is recommended that the command offenable 0 be issued early in any autoexec.btf start-up batch file. Command RD Remove directory (RD) RD path Deletes a directory, including any files in it (and subdirectories). Note that, in contrast to MS-DOS, there is no requirement to delete all the files in a directory before removing the directory. Further, no warning is given before the directory is removed. HC PROGRAMMING GUIDE In another difference from MS-DOS, it is perfectly possible, in the HC Command Shell, to remove the directory where the current path is. All that will happen is that subsequent commands such as dir may fail until such time as the current path is changed. As files and directories are deleted, their names are listed on the screen. The rd command does not accept a wildcard specification. This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which result, in the end, in calls to the C function p_delete. Command RENAME Rename file(s) (RENAME) REN[AME] filespec filename Changes the name of a file or files. The command renames all files matching filespec - which can include wildcards. For example, the command ren work.* play.* changes the names of all files called work in the current directory (regardless of extension) to play, with the extension being preserved across the rename. As files are renamed, they are listed on the screen. Because it is not possible to rename files from one directory to another, the command fails if any path specified with filename (explicitly or implicitly) differs from that of filespec. It is not possible to rename a file to have the same name as a file that already exists. This command is implemented via object-oriented techniques using the fman object in Olib.dyl, which result, in the end, in calls to the C function p_rename. Command RESUME Resume a suspended process (RESUME) RES [UME] procname Resumes the previously suspended process procname. See also suspend, Some care needs to be exercised in the use of this command, to resume an instance of process job (say), in any case where there may be more than one instance of job running at a time. This is because the command simply attempts to resume the first instance of the process job found, regardless of whether or not that particular process is actually suspended. This command is implemented via the C function p_presume. Command SET Set default path (SET) Sets the default path. For example, the command set b:\ has the effect that all subsequently launched tasks start with their current paths set to b:\. This may be useful if a program assumes that its current path on start up is where it should read and/or write certain files. See the earlier section Files and directories for further discussion. This command is implemented via the C function p_setdefaultpath. Command SETDATE Set time and date (SETDATE) SETD[ATE] dd/mm/yy hh:mm:ss Sets the date and time. For example, setdate 26/02/92 15:10:00 sets the date to the 26th of February, 1992, and the time to ten minutes past three in the afternoon. 3-16 3 HC COMMAND SHELL All parameter fields must be present, with a two digits being supplied for each field. The time should always be specified in 24 hour format. If yy is in the range 70 to 99, the century is set to 19. Otherwise it is set to 20. That is, the range of years that can be set is from 1970 to 2069. This command is implemented via the C function p_sdate. Command SUSPEND Suspend a process (SUSPEND) SUS[PEND] procname Suspends the first process found matching the specification in procname. To suspend a specified instance of a number of running tasks, all with the same name, the exact process name must be found out and used. Eg suspend job.$09 OF suspend job.$14. If only one instance of job.img is running, it suffices to enter suspend job. Use the 1proc command to give the full process names of all current processes. Use the resume command to reverse the effect of a suspend command. This command is implemented via the C function p_psuspend. CommandTERMINATE Terminate a process (TERMINATE) TER[MINATE] procname Terminates the first process found matching the specification in procname. To terminate a specified instance of a number of running tasks, all with the same name, the exact process name must be found out and used. Eg ter job.$09 Of ter job.$14. For most applications, the effect of being terminated is identical to being killed: the application is interrupted immediately, with no chance being provided for data being saved to file or to environment variables. However, an application can make use of an operating system service (in C, p_onterminate) to specify behaviour to be invoked whenever the application is to be terminated in this way. This command is implemented via the C function p_pterminate. Command TYPE Type a text file (TYPE) TY[PE] filename Prints a text file to the screen. There is no provision for the display to pause itself automatically. However, the user can pause the display at any time, in the usual way, by pressing PSION+LEFT. This command is implemented via the C functions p_open (P_FTEXT) and p_read. Command VER Display software version number (VERSION) [VER] SION Displays the Operating System (Epoc) version number, the HC Rom version number, and the Command Shell version number. This command is implemented via the C functions p_version and p_romversion. Command WAIT Wait for a process to complete (WAIT) WAI [T] Waits until a process completes. The message "Waiting" is displayed and the Shell becomes non- interactive until such time as another process completes. To break out of this mode, press PSION+ESC. HC PROGRAMMING GUIDE Commonly, this command will be used inside batch files in the following general pattern: wait Command WNOTIFY Configure Notifier appearance (WNOTIFY) WNO[TIFY] state Configures the appearance of the Notifier. If state is orr, the Notifier will be drawn in the same way as it was for software versions prior to release 1.50 of the HC ROM. (This is the default.) If state is on, the Notifier will be drawn in an arguably more attractive form, and will also be displayed automatically whenever any program terminates abnormally. This form of the Notifier also involves less RAM usage. The w in the name wnotify stands for Window Server - the part of the operating system which actually produces the more attractive version of the Notifier display. To see what a Notifier looks like under either of the two methods, first terminate Link (if it is running) and then type (eg) link x This brings about a "File does not exist" Notifier, since the file x.trm (presumably) does not exist. This command is implemented via the C function wsystem (amongst others). Using the command fre before and after typing wnot on should reveal a memory saving of around 7 Kbytes. What happens when the Command Shell starts Exactly what happens when the Command Shell starts depends on whether it has been passed a command line. When the Shell is started by the Window Server (after a reset, for example), no command line is passed. In most other cases, however, the user would pass a command line to the Shell. For example, typing run sysSshll /p ver into MCLink has the effect of running a copy of sys$shl/ on a remote HC, passing it the command line /p Vers When no command line is passed The Command Shell checks to see if a process sys$ntfy is already running. If not, it launches one from the HC ROM. (However, if the Window Server has taken over the notifier function, the independent sys$ntfy.img process will quickly discover this fact, and terminate itself silently.) Similarly, the program batchk is launched, if it is not already running. Next, the Command Shell searches for a batch file autoexec.btf and executes that, if one is found. The search is on the root directories of a:, b:, and m-, in that order. If no such batch file is found, the user is prompted to insert an SSD containing this file, and to press ENTER to continue. However, the search can be abandoned by pressing PSION+ESC instead. 3 HC COMMAND SHELL Then some system information is displayed on the screen: the version numbers of the ROM-resident software, the date and time, the size of the display screen, the battery type and internal power supply type, the reason why the operating system was last restarted, and the size of the RAM and how much of it remains free. C functions involved in the start-up display (in addition to those mentioned in the above alphabetical listing) include p_getlcd, p_getbat, p_getpsu, and p_getres. The final thing the HC Command Shell does, before starting to process commands from the user, is to attempt to capture the OFF key to itself. 3-19 CHAPTER 4 THE HC IN THE CRADLE Introduction The Psion Cradle was designed to provide: e asecure mounting for the HC. e hands-free operation. e battery recharge. e high speed data transfer with a PC. The cradle automatically engages with the high speed serial port on the HC and can be connected via a high speed cable to a PC. Running special software on the PC enables a high speed serial connection that is significantly faster than the standard serial connections described elsewhere. See the chapter Introduction to the HC for additional background details about the Cradle. Port C The Cradle contains an expansion socket that can accept some, but not all, of the HC's standard expansion modules. This expansion socket has name "Port C" as seen by software (the two standard HC ports have names "Port A" and "Port B". For example, software that opens Try:c will open any serial port in the Cradle expansion slot. Link software can use a standard serial port fitted into the Cradle. The Link software must be invoked as follows: link -p3 -b9600 This allows the Link software to operate at standard rates of data transfer, i.e. up to Baud 9600. The remainder of this chapter describes various kind of higher speed connections that are possible between a PC and an HC. These require the expansion port of the Cradle to be fitted with a special high speed serial module. Note that this module will not operate if it is connected into either Port A or Port B of an HC - it has to be fitted into Port C. Hardware connections The high speed cable plugs into a special socket on an ASIC-2 expansion card fitted in the PC. The remainder of this chapter assumes that the PC has an ASIC-2 expansion card fitted, and that the high speed cable connects into this card. Fitting an ASIC-2 expansion card An ASIC-2 expansion card in a PC contains two sockets: e the upper one is designed to be connected to a (local) set of SSD drives e the lower one is designed to be connected to a high speed cable leading to an HC Cradle. HC PROGRAMMING GUIDE The two possible uses of an ASIC-2 card in a PC are completely independent from each other. Any local SSD drive can be accessed as long as software device drivers such as devram.sys have been loaded by the config.sys program on the PC (the drivers ifs.sys, fefs.sys, and devflash.sys also need to be loaded to access Flash SSDs in these drives), none of these drivers are required for the high speed socket to work. The ASIC-2 card occupies eight consecutive memory addresses, and uses one hardware interrupt. A set of jumpers on the card controls these two settings. The standard ASIC-2 card works with MS-DOS versions 3.2 upwards. It is suitable for all PCs, XTS, ATs, and fully compatible computers. A variant of the card is also available for MCA-based computers, such as most PS/2 models. Full details of installing and configuring the ASIC-2 card are contained in the documents Installing the Psion SSD/ fast serial card for PCs and Installing and using the Psion SSD software and SSD drive unit for PCs that accompany the ASIC-2 expansion card. Software connections There are two quite separate software mechanisms for connecting an HC in a Cradle to a PC with an ASIC-2 expansion card: ¢ running suitable Link software on each end of the connection, allowing high speed remote file access between the two computers e using the pmx: device driver on the HC and the hssram.sys device driver on the PC, allowing RAM SSDs in the HC to be accessed from the PC as if they were SSD drives directly connected to the PC. At the time of writing, the remote file access supported by the ASIC-2 card allows data transfer on average about four times faster than that possible using a standard RS232 serial connection between an HC and a PC. The PMX/HSS mechanism allows data transfer that is considerably faster than this. However: e the PMX/HSS mechanism only allows access to RAM SSDs in the HC, not (at the time of writing) to Flash SSDs, nor to the "internal" drive (m-) e the PMX/HSS mechanism only allows access to the HC SSD drives from the PC: there is no question of access to the PC drives from the HC. Evidently, the two different mechanisms are both well-suited to different circumstances. Check with Psion on the availability of a driver hssflash.sys allowing access to Flash SSDs in the HC. High speed remote file access using Link software In order for Link software on the HC and on the PC to use the high speed connection, the parameter -stty:z needs to be specified. Thus at the HC end: e any current Link software should be terminated, using the command term link. e Link software should then be started (or restarted), using the command link -stty:z. At the PC end, the same parameter should be passed on the command line to MCLink. To check that a connection has successfully been established, simply type dir rem:: at either end. In both cases, other parameters on the command line (such as an explicit value for the Baud rate) will generally be ignored. As is standard for Link and MCLink software, command line parameters can be specified implicitly by creating .tvm files. For example, any parameters in a local file mclink.trm (as created by a set command inside MCLink) will apply, in the absence of any other contents on the command line. For more details, see the chapter Mclink, Mcprint, and Slink in the Additional System Information manual. Version 3.0 or higher of MCLink is required, in order for the -stty:z parameter to be recognised. 4-2 4 THE HC IN THE CRADLE High speed debugging using Link software The Sibo Debugger can use a high speed connection to cut down on the time spent in data communication between the PC (where the Debugger runs) and the HC (where the program being debugged runs). For general information about the Sibo Debugger, see the Sibo Debugger manual. As always when using the Sibo Debugger, Link software has to be running on the HC. In order for the Link software to use the high speed connection, the parameter -stty:z has to be specified: link -stty:2 The same parameter has to specified on the command line of the Debugger. Thus instead of typing e.g. \sibossdk\sys\sdbg sample to debug the program sample.img, the following should be typed: \sibosdk\sys\sdbg -stty:z sample The PMX/HSS mechanism If the following line (or equivalent) is placed in the config.sys start-up program for a PC device=c:\ssd\hhsram.sys and the PC has an ASIC-2 expansion card fitted, the PC will gain four more disc drives. If the PC ordinarily has floppy drives a: and b-, and a hard disk c:, then drives d: through g: will be added by this process. However, typing e.g. dir da: at the MS-DOS command line would almost certainly lead to a message such as Not ready reading drive D: Abort, Retry, Fail This is because pmx: software has not yet been enabled at the HC end of the connection. Incidentally, two definite effects of running the hssram driver on the PC can clearly be seen, even in the absence of co-operating pmx: software on the HC: e typing dir d: gives an error message of the above sort, whereas typing e.g. dir h: leads to the more cursory message Invalid drive specification e if there is a hardware connection between the PC and the Cradle, and if there is an HC in the Cradle, the green "Data" light will flash when the dir d: command is given. Configuring hssram.sys The document Installing and using the Psion SSD software and SSD drive unit for PCs that accompanies the ASIC-2 card for PCs describes how the base address of the ASIC-2 card can be altered, by means of adjusting jumpers on the card. This adjustment may occasionally be necessary, away from the default base address of 0x2a0 and hardware interrupt 7, in order to avoid conflicts with other expansion cards already fitted in the PC (for example, network cards or internal modems). In this case, as well as adjusting the jumpers on the ASIC-2 card, you will need to change the configuration of some of the associated software drivers. When using an SSD drive unit with the ASIC-2 card, the software driver devram.sys needs to be reconfigured (if the jumpers are adjusted). This is fully described in the document Jnstalling and using the Psion SSD software and SSD drive unit for PCs. When using the high speed connection to a HC in a Cradle, it is the software driver hssram.sys that needs to be reconfigured (if the jumpers are adjusted). The new configuration is established in exactly the same way as for devram.sys, except that every reference to devram.sys has to be replaced by one to hssram.sys. HC PROGRAMMING GUIDE For example, to change the base address to 0x370 type the following: ok cd \ssd config -a0x370 hssram.sys In practice the default settings of the jumpers and of the ASIC-2 card should be suitable for the vast majority of PCs. In case it is known to what base address the card should be set, but it is unclear how the jumpers should be set to effect this, simply run the config program specifying the required base address (and/or hardware interrupt number). The output of the config program specifies which of the nine jumpers on the card should be set. The PMx: device driver The following very simple program demonstrates the operation of the PMX: device driver: #include #include #include LOCAL_C VOID GetKey (TEXT *mess) { p_printf("Press a key to %s PMX:",mess); p_printf("(PSION-ESC to terminate)"); p_getch (); } GLDEF_C VOID main(VOID) { VOID *handle; FOREVER { GetKey ("open") ; p_open(&handle, "PMX:",-1); GetKey ("close"); p_close (handle) ; } } Basically, so long as the pmx: device is open by an application on the HC, any RAM SSDs in the HC will be inaccessible to the HC filing system. Attempting to read from these SSDs will give a "Not ready" error. Instead, these drives are given over to the control of any high speed serial requests from the PC. Thus whilst the pux: device is open, typing e.g. dix d: at the PC end of the connection will give a directory listing of the contents of any Ram SSD in drive a: of the HC. Likewise, typing dir e: at the PC will list the contents of any Ram SSD in drive b: of the HC (this assumes that hssram.sys has been installed on the PC and that there is only one hard disk partition on the PC). When the pmx: device is closed again, the Ram SSDs in the HC come back under the aegis of the HC, and the familiar "Not ready” message will be given in response to an attempt to access these drives directly from the PC. More details about PMX The pmx: device driver has no interface other than the p_open and p_close functions used in the above code fragment. It is possible for the p_open to fail, with the following errors: E_FILE_ALLOC failed to allocate memory for the control block E_GEN_INUSE the px: driver is already open (e.g. in another application), or the high speed port is already in use (e.g. by high speed Link) E_FILE_LOCKED same as the previous case. 4-4 4 THE HC IN THE CRADLE The CRD device driver The cro: device driver, which is built into the ROM of the HC, can be used to report changes of state when an HC is inserted or removed from a Cradle. The purpose of the cro: device is to allow a program to perform specific operations automatically when the HC is inserted into a Cradle, and to "tidy up" when the HC is removed. Note that the crp: device does not have to be open for the Cradle expansion port to be used in any way. The operating system will automatically stop and start active devices in the Cradle, regardless of whether CRD: is open. See the HC Cradle and Holster chapter of the I/O Devices Reference for more details of using the cro: device in HC programs. In fact, the crp: device has a particularly simple interface (though not quite as simple as that of pmx:, described earlier in this chapter). The entirety of the functionality of crp: when used with a Cradle is demonstrated by the following example program: include include include LOCAL_D WORD CradleStatus; LOCAL_D WORD CradleStat; LOCAL_D VOID *Cradle; LOCAL_C VOID ReadCrdStatus (VOID) p_ioc4 (Cradle, P_FREAD, &CradleStat, &CradleStatus) ; } GLDEF_C VOID main(VOID) { if (p_open(&Cradle, "CRD:",-1) ) { p_puts ("Can't open CRD:"); p_getch (); p_exit (0); } ReadCrdStatus (); FOREVER { p_iowait (); p_puts (CradleStatus? "IN Cradle": "OUT of Cradle"); ReadCrdStatus(); } } In practice, of course, there would be more than one event source in the application (the only events in the above example application are when the HC is inserted or removed from the Cradle). 4-5 CHAPTER 5 CUSTOMISING THE HC ROM Introduction HCs are shipped with a standard set of software programs in their rom. Application programs usually reside on SSDs which the user has to insert into the HC. These application programs generally rely on the ROM software in many ways, both direct and indirect. For some purposes, however, it may be more suitable to alter the set of software programs that is on the ROM of the HC: e programs run out of ROM have less of a RAM overhead than those run from an SSD e programs in the ROM are physically more secure than those on an SSD, in the sense that an SSD can be removed by a user but the ROM cannot ¢ programs in the ROM may be able to take advantage of special software features inaccessible to programs on an SSD - for example, the fact that ROM code and data segments always remain at a fixed address ¢ programs in the ROM are easier to copy-protect. All the different files comprising an HC ROM need to be assembled on a PC, and then combined into a special master file, with extension .mas. This process involves the Psion proprietary tool erom.exe. The next step is to copy the master file onto a specially formatted SSD. This requires the use of an SSD drive attached either internally or externally to the PC, and the Psion proprietary tool emast.exe. The outcome of this is a so-called master SSD. Finally, the .mas file can be transferred from the SSD into the ROM of an HC, by the procedure of reprogramming (or reproing for short). Some cautionary remarks The process of creating customised HC roms is not without its own considerable drawbacks: e the sheer inconvenience of reproing every relevant HC, each time the customised ROM software is upgraded, has to be weighed against the simpler alternative of just copying new program files onto an external SSD e reproing "in the field" is an impractical option, given that mains adaptors (which must be present for a repro to proceed) are unlikely to be present or usable in these circumstances e acustomised ROM may fail to be "future proof" in that future upgrades to the standard OS may reduce the free space in the ROM to the extent that additional custom software no longer fits e¢ again, a customised ROM may fail to be "future proof" against growth within the customised part of the ROM - bear in mind that program systems almost inevitably develop over time and grow in size as they develop e acustomer who damages an HC will find it is less convenient to have it replaced or repaired if it has been specially customised, than if it is a standard stock item HC PROGRAMMING GUIDE e if an unsuitable combination of files is combined into a.mas file, the outcome of reproing this onto an HC may be a totally useless HC, that has to be returned to Psion and taken apart before being capable of being used again (and note that HCs returned to Psion on account of a repro failure in these circumstances would count as having violated the standard warranty conditions). Incidentally, in the last of these above cases, it may be possible to rectify the situation by means of putting another Window Server onto an SSD and rebooting the HC. This is because any program sys$wsrv.img that is found on the root directory of an SSD is started in preference to that in the rom. At a simpler level, putting an alternative shell (sys$shll.img) on an SSD and rebooting may also salvage matters. Perhaps the largest drawback of all has not been mentioned so far. This is the possible effort required to produce software sufficiently small that it fits on the available space remaining in the HC rom. In practical terms, this may mean "optimising" and compressing code to the extent that it becomes unmaintainable or otherwise flawed. However, it may still be worthwhile putting part of a customised software system into the ROM of an HC, instead of all of it, so that at least some of the benefits mentioned earlier can be gained. Creating an HC master file Invoking erom The program erom.exe is used to create the master file image of the HC rom. As so many parameters must be passed it is usually invoked via a short batch file. The following batch file mrchv.bat could be used: erom >sch.mep -c -m —b0xa000 -v0x033e -lsch -oENG epocchp type sch.mep This batch file records its screen output to the file sch.mep, before printing the contents of this file onto the screen. The meanings of the other parts of this batch file are as follows: -c the ROM is to be marked as suitable for reproing onto HC computers (as opposed to others in the Sibo range). -m the ROM image should be written to a .mas file. -b0xa000 the ROM is to have base address 0xa000 in the address map. -v0x033e the version number of the ROM is to be 0. 33e. -lsch the files listed in the text file sch.rom are to be assembled into the rom. -oENG the notional language of the ROM is English. epocchp the ROM is to be based around the version of Epoc that is in the file epocchp.exe. The master file produced by this batch file, if successful, would have name v033eeng.mas. This name is made up as follows: e the first letter is always v. e the next four letters are the version number (in this case 033e). e the final three letters are the notional language identifier. Allowed values of language identifier include: ENG "English" FRN "French" GRM "German" SPA "Spanish" ITA "Ttalian" SWE "Swedish" DAN "Danish" DUT "Dutch" 5-2 5 CUSTOMISING THE HC ROM In fact, erom.exe will fail if an unrecognised language identifier is specified. Note that the language thereby identified has a purely notional role, being announced only during the process of reproing, when the user is given a last chance to cancel before the ROM contents are changed (the actual value of language, as determined by software calling p_get language, is set by the contents of one of the files in the rom). Valid version numbers See the documentation of p_version and p_romversion in the Plib Reference manual for some background details on valid version numbers. Note that whereas roms produced by Psion are generally released with a version number ending in f, those produced by erom.exe are automatically constrained to a final letter in the range a to e. This is to help guard against any confusion between customised roms and those produced by Psion. One other feature of the roms produced by erom.exe is that they always contain a zero-length file with the name non$std.rom (in addition to the files specified in the sch.rom file). The files comprising the rom In order to produce a standard HC rom, the contents of the list file sch.rom referred to by the batch file mrchy.bat would have to be as follows: cheng.cfo,sysS$ctry.cfo wsrvhchl.img, sys$wsrv.img corpshll.img, sys$shll.img corpntfy.img, sysS$ntfy.img sysSenv.ini sysS$rfsv.img sysSncp.img link.img mclinkpa.trm, mclink.trm olib.dyl big.fon small.fon mon_5x8.fon mono.fon sysSnorm.fon sysSbold.fon exopl.img oplch.dyl,opl.dyl batchk.img ttest.img pprint.img custom$.dat The form of any line in this file is as follows: [, ] These files have the following functions (see elsewhere in the HC Programming Guide for more details): cheng.cfo The standard English language "config file" for the HC (non-backlit variant) wsrvhchl. img The Window Server program for the HC corpshll.img The Command Shell corpnt fy.img The original (non-Window Server) Notifier program for the HC sys$env.ini Initialisation data for the Window Server sys$rfsv.img The Remote File Server program sys$ncp.img The Networking Control Protocol program used by Remote Link link. img The Link program mclinkpa.trm Standard customisation data for Remote Link on the HC olib.dyl A dynamic library of object-oriented classes and methods HC PROGRAMMING GUIDE *. fon Six different font files exopl.img A program facilitating the execution of Op! programs oplch.dyl The Opl dyl for the HC (implementing Opl/g) batchk. img Displays and monitors information about battery voltage levels ttest.img A utility program to test the status of the serial port pprint.img A utility program to print a specified file via a nominated peripheral custom$.dat An initially blank file that can be written to after reproing has finished, to allow additional once-only customisation. Of these files, the only one that it is absolutely mandatory for the ROM to contain is a version of the config file, sys$ctry.cfo. All others can in principle be dispensed with, though some can be replaced more easily than others - as is discussed below. Size considerations The following extract from a standard .mep file (the "list" output of running erom.exe) may give some idea as to the current amount of free space in the HC rom: CHENG. CFO - B=B832 L=010FD (Hex) , 004349 (Dec) WSRVHCH1.IMG — B=B942 L=085C0 (Hex) , 034240 (Dec) CORPSHLL. IMG - B=C19E L=03D30 (Hex) , 015664 (Dec) CORPNTFY.IMG - B=C571 L=007A0 (Hex) , 001952 (Dec) SYSSENV.INI - B=C5EB L=00060 (Hex) , 000096 (Dec) SYSSRFSV.IMG - B=C5F1 L=004F0 (Hex), 001264 (Dec) SYSSNCP.IMG - B=C640 L=02330 (Hex) , 009008 (Dec) LINK. IMG - B=C873 L=O00ADO (Hex) , 002768 (Dec) MCLINKPA.TRM - B=C920 L=000E2 (Hex) , 000226 (Dec) OLIB.DYL —- B=C92F L=04828 (Hex) , 018472 (Dec) BIG.FON - B=CDB2 L=O00BCE (Hex) , 003022 (Dec) SMALL.FON - B=CE6F L=0093E (Hex) , 002366 (Dec) MON_5X8.FON - B=CF03 L=0093E (Hex) , 002366 (Dec) MONO .FON - B=CF97 L=00918 (Hex) , 002328 (Dec) SYSSNORM. FON - B=D029 L=0093E (Hex) , 002366 (Dec) SYSSBOLD.FON - B=DOBD L=0093E (Hex) , 002366 (Dec) EXOPL. IMG - B=D151 L=002C0 (Hex) , 000704 (Dec) OPLCH.DYL - B=D17D L=054C6 (Hex) , 021702 (Dec) BATCHK. IMG - B=D6CA L=00750 (Hex) , 001872 (Dec) TTEST.IMG - B=D73F L=00F40 (Hex) , 003904 (Dec) PPRINT.IMG — B=D833 L=00850 (Hex) , 002128 (Dec) CUSTOMS .DAT —- B=D8B8 L=01800 (Hex) , 006144 (Dec) Rom Base Segment is 0A000 (Hex ) Rom code size is 18150(Hex) 098640 (Dec) Rom disk size is 22230(Hex) 139824 (Dec) Free rom size is 05C60(Hex) 023648 (Dec) Note that the length of each file listed is given by the "L" value - first in hex, then in decimal - and the corresponding notional base address is given by the "B" value. As can be seen, the amount of free space in the standard HC ROM is about 23k. However, this figure can be increased by omitting some of the files normally included. Some possibilities for customisation An alternative shell Rather than using corpshll.img, a customised version of the shell program may be substituted. This alternative shell can have any suitable name (eg datashll.img), so long as the extension is .img and the .rom file renames the shell to sys$shll.img. See elsewhere in the HC Programming Guide for further details of writing a customised shell. 5-4 5 CUSTOMISING THE HC ROM Variant config files Replacing cheng.cfo with chengel.cfo changes from the non-backlit variant to the backlit variant of the keyboard table (in fact altering the value of the keycode returned to software when the middle of the three salmon-coloured keys on the top row is pressed). Similarly: chfrn.cfo produces a ROM suited to the continental version of the keyboard, supporting some accented characters such as é chswe.cfo produces a ROM suited to the Scandinavian version of the keyboard, supporting characters such as « chnzl.cfo produces a ROM suited to the numeric version of the keyboard. There are also files chfrnel.cfo, chsweel.cfo, and chnzlel.cfo, which are backlit variants of chfrn.cfo, chswe.cfo, and chnzl.cfo. Config files in .cfo format are produced from text format .fig files using the Psion proprietary tool econfig.exe, details of which are available upon request. Additional files that might be added As many additional program (or data) files can be added as will fit in the rom. To make room for these files, other files in the standard ROM may have to be omitted - see below. Files that might be omitted It is possible to omit any reference to sys$ntfy.img from the ROM file list provided that an alternative shell is used. This shell must make a suitable call on start-up to wsystem so that the Windows server version of the notifier is enabled. Alternatively suitable values must be written into sys$env.ini (see below). The files ttest.img and pprint.img can each be omitted without any undue loss. The file custom$.dat can be omitted if there is no intention to further customise individual HC roms afterwards. Alternatively, a shorter form of this file can be substituted (every single byte in this file must have the value oxf£). The file batchk.img can be omitted or replaced with alternative battery checking software. In this case, it is best not to use corpshil.img, as this emits an error message on start-up if it cannot locate and run a copy of batchk.img. The files exopl.img and oplch.dyl can be omitted if there is no need to run Opl programs on the HC. Some of the .fon files can be omitted, provided due care is paid to provide a suitably adjusted sys$env.ini (see below). For example, the MC-derived fonts big.fon, small.fon, and mono.fon could be omitted, leaving only mon_5x8.fon and the Series3-derived fonts sys$norm.fon and sys$bold.fon. Note that the order of listing .fon files in the .rom file defines which fonts correspond to which Window Server font ids - wS_FONT_BASE specifying the first .fon file in the .rom listing, and so on. Note also that the HC console (as used by C programs containing statements like puts or p_printf, and also by print statements in Opl) presupposes the use of the third .fon file listed, so that this should always be mono-spaced and of size 5 by 8. Customising the Window Server Whenever the system restarts, the Window Server reads the contents of sys$env.ini, and sets environment variables according to the data therein. Dumping the contents of the standard sys$env.ini will confirm that a particularly simple format is used in this file: [] with this pattern being repeated as many times as there are environment variables to initialise. For each such environment variable, the byte count preceding the environment variable name gives the length of the name, and the byte count preceding the environment variable value gives the length of the value. HC PROGRAMMING GUIDE The only environment variables that you need to consider defining in sys$env.ini are the following: $WS_SF gives (in two bytes) the index number of the .fon file to use as the "system" font, which is the default font for all drawing via any GCs (graphics contexts). This will usually be left at value 0, and as such can be omitted from sys$env.ini. $WS_IF gives (in two bytes) the index number of the .fon file to use as the "internal" font, which is what the Window Server uses when drawing alerts, busy messages, and information messages. This has the value 4 in the standard sys$env.ini, thereby specifying sys$norm.fon as the internal font. In case an alternative .rom file omits big.fon and moves sys$norm.fon into this slot, the value of sws_1F should be adjusted to 0. $WS_FL gives (in two bytes) the initial value of the Window Server flags. This is zero in the standard sys$env.ini. See the System start-up section in the Window Server Reference manual for more details of the possible Window Server flags. In many cases, the initial value 0x0a will be appropriate, setting the flags _NO_NOTIFIER_REBOOT and _HOOK_NOTIFIER. Creating and using a master SSD Once a suitable .mas file has been created, the next step is to transfer it, together with the repro software, onto a master SSD. This requires an SSD drive to be attached to the PC, although no special software drivers (such as fefs.sys and devflash.sys) need to be installed. Anyone ordering an SSD drive for their PC should note that, for it to function, not only is the drive itself required, but also an ASIC-2 expansion card, and (in the case of an external SSD drive) a suitable connecting cable. The master SSD is usually created under the control of a batch file, of which the following (makemast.bat) is an example: @echo off emast —-ul v033eeng.mas echo Transferring other software... xcopy \hcmast\*.* £:\*.* /s This potentially copies a whole directory tree onto the master SSD, i.e. the contents of Vicmast\ including subdirectories. In this case, the contents of Vicmast\ would include repro.app. The batch file assumes that the PC sees the first SSD slot as drive £:, and would need to be altered if this is not the case (changing f:\ to eg e:\). The batch file also assumes that all relevant software drivers for the external SSD drives have been loaded. The -u1 parameter to emast specifies that the top left SSD slot in the attached SSD drive is to be used. The filename passed to emast obviously has to match that of the master file created earlier by erom. Once the batch file has finished, the SSD can be used to repro HCs in the normal way. More details on master SSDs A master SSD must be a 512k Flash device and has a very special format: part of it is devoted to a "file" that is outside the filing system proper, and the remainder (just under 256k) is presented to the outside world as if it were the entirety of the SSD. That is, normal file operations do not see the .mas "file" that is on the SSD. This is why the .mas file has to be copied onto the SSD using a special tool, i.e. emast.exe. This tool not only copies on the .mas file but also specially formats the remainder of the SSD. To repro numeric keyboard HCs To prepare a master SSD that can be used to repro an HC with a numeric keyboard (and which therefore lacks keys such as R, E, P, and 0), a copy of repro.app should be renamed to yOn0.img before being copied onto the master SSD. 5 CUSTOMISING THE HC ROM Files required This section lists the files from the Optional Disk of the SDK that are needed, in order to be able to produce a customised ROM for the HC: source files: mrchy. bat, sch.rom, epochhp.exe, repro.app, makemast.bat, and the 22 files listed above as the standard contents of a .rom file, i.e. cheng.cfo through custom$.dat, together with the other 7 standard .cfo files tools: erom.exe and emast.exe. APPENDIX A TECHNICAL SPECIFICATIONS Psion's continuing product development and improvement programs mean that specifications and features are subject to change at any time and without notice. Psion Solid State Disks Technical Specification Dimensions Size: 63mm (length) x 52mm (width) x 6mm (height) Weight: =25¢ Capacities RAM: 128KB, 512KB, IMB, 2MB Flash: 128KB, 256KB, 512KB, IMB, 2MB, 4MB, 8MB PSRAM: 512KB, IMB, 2MB Solo Flash: 128KB, 256KB, 512KB Filing System Flash, RAM and PSRAM: MS-DOS RAM and PSRAM: FAT directory/file system Interface Physical: 6 pin serial Electrical: Clock, OV, V, V_. V_., Data backup’ ° pp’ * cc’? Data Transfer SSD interface: 320Kbytes/sec File Access Note: the quoted rates for the Series 3c also apply to the Siena with external SSD drive All SSD types read: 30-40Kbytes/sec depending on SSD/directory structure (HC and Series 3c) Flash write: =6Kbytes/sec (HC), =8Kbytes/sec (Series 3c) RAM and PSRAM write: 30-40Kbytes/sec depending on SSD/directory structure Formatting Flash: =30 secs per 128K (HC), =20 secs per 128K (Series 3c); 9,999 times minimum Format/write voltage: 12V DC Programming voltage: 15.0V to 18.0V DC on the Vh pin @ 40mA max. (type II flash) RAM: 7.5 secs per 128K (HC), =6 secs per 128K (Series 3c) Power Flash, standby: S500uA RAM, standby: 10uA Flash and RAM, reading: 1mA Flash, writing: 20-30mA RAM, writing: =ImA HC PROGRAMMING GUIDE PSRAM versus SRAM SSDs Important: Pseudo-Static RAM (PSRAM) SSDs are not recommended for use in consumer machines, (Series 3a, Series 3c and Siena). This section explains why. PSRAM SSD's are not suitable for use with some machines: HC Yes (with an upgrade - see below) HC-DOS Yes (with an upgrade - see below) Workabout Series 3 (all variants) Series 3a 256K, 512K i The fact that PSRAM SSDs can only be used with the IMB and 2MB Series 3a is effectively a No to the Series 3 range, because of the problem of having to differentiate the various Series 3 models at point of sale. PSRAM SSDs are therefore only recommended for use in Psion Industrial’s handhelds. An upgrade to both HC and HC-DOS machines (involving a component change on the main PCB only) is in progress. HC and HCDOS machines supporting PSRAM SSDs will be identifiable by their serial number. The performance of the upgraded machines is not affected in any other way, including power consumption and use with any peripherals and other SSD types. All SSD's have a common serial interface which sets the data transfer rate. This means that for reading and writing data, all types of RAM SSDs work at the same speed. The power consumption of a PSRAM chip is generally higher than for the equivalent Static RAM (SRAM) chip when read/writing data. However, both types of memory only transfer data during a small part of the SIBO cycle so the power consumption of an active SSD is not much higher for a PSRAM as opposed to an SRAM. However, a PSRAM SSD consumes a significant amount of current when the host machine is turned on, even though no data is being transferred. This is because an oscillator is required to refresh the memory. This can increase the overall current consumption of the machine by up to a third. Also, when the host machine is off, the backup current of the PSRAM SSD is much higher than the equivalent SRAM SSD. A lithium cell in a 2MB PSRAM will have a life of about 17 days (400 hours) outside a SIBO machine. PSRAM SSDs are best considered as memory expansion rather than removable media and are most suited to applications where they remain inside a machine; then they only rely on their backup batteries when the machine's main battery is changed. PSRAM SSDs should therefore only be used in applications where the above disadvantages have little affect. An example is a Workabout which is mostly powered/recharged through insertion into a docking station and whose SSDs are never removed. APPENDIX A TECHNICAL SPECIFICATIONS Psion HC Technical Specification Models Psion HC100: Psion HC110: Psion HC120: 128K CMOS static RAM. 256K CMOS static RAM. 512K CMOS static RAM. All models have 256K internal Flash ROM. Processor Type: Clock: Dimensions Size: Weight: Environmental Temperature: Humidity: Weatherproofing: Drop resistance: EMC: Safety: Software Operating system: Command shell: Communications: Printing: Solid State Disks Built-in drives: SSD capacities: Filing system: File Access 80C86-compatible 16-bit processor. 3.84MHz. 200mm (length) x 80mm (width) x 35mm (height). 395g (540g with batteries but no SSDs). Operating OC to +50C, storage -20C to +70C. Operating 90% max non-condensing. IP54. Splashproof (depending on variant). 1 metre onto concrete. FCC Class B; CE marked, E-marked. EN60950. Psion EPOC multitasking OS. MS-DOS like command interpreter Psion LINK, 50-9600 baud, asynchronous, compatible with MCLINK, RCOM & PSIWIN software on remote PC. Parallel and serial and via remote PC. Two SSD drives. Flash: 128KB, 256KB, 512KB, IMB, 2MB, 4MB, 8MB RAM: 128KB, 512KB, 1MB, 2MB. MS-DOS compatible. Note: the quoted rates apply only to the HC. Flash read: RAM read: Flash write: RAM write: Formatting Flash: Format/write voltage: RAM: Screen Type: Resolution: Dimensions: Keyboard Alphanumeric: Numeric: Custom: 30-40Kbytes/sec depending on SSD/directory structure. 30-40Kbytes/sec depending on SSD/directory structure. ~6Kbytes/sec. 30-40Kbytes/sec depending on SSD/directory structure. =30 secs per 128K. 12V DC. 7.5 secs per 128K. Black and white retardation film LCD, optional back lighting. 160 X 80 pixels, 26 characters x 9 lines (default font). 60mm (width) x 50mm (height). 53 key UK/US, European and Scandinavian versions. 31 key with function keys. Can be provided. HC PROGRAMMING GUIDE Sound Built-in: Power Main battery: Back-up: External: Battery life: Expansion Capabilities: Modules: Piezo buzzer (single tone) and loudspeaker. NiCad 500mAH or 600mAH rechargeable pack. CR1620 3V lithium cell. 12V DC via Psion adaptor. Typically up to 50 hours, depending on use and configuration. Two expansion module interfaces. RS232/Parallel; Quad Modem; MCR/RS232/TTL-RS232; Bar Code Reader; RS232/TTL-RS232; RS232/Bar Code Reader; Printer; LIF-PFS/Barcode; LIF-PFS/TTL-RS232; 16550 RS232/TTL-RS232; Vehicle/TTL-RS232; Integral Laser Scanner. Psion HC RS232/Parallel (printer) module, version 1 Technical Specification Important Notice - Compatibility This module can continue to be used in both top and bottom ports of the HC. Applications requiring serial or parallel comms from the HC should use this module. This module can be used in the Workabout Docking Station for serial or parallel communications. This module must not be used in an HC Docking Station sold in countries requiring the CE Mark. The version 2 Psion HC RS232/Parallel (printer) module must be used instead. Physical Part number: Module: HC compatibility HC-DOS compatibility Docking station compatibility EMC: Safety Connectors RS232: Parallel: Serial Interface Baud: Data bits: Stop bits: Parity: Handshaking: Remote switch-on Protocols: 1502-0001 Integrated removable module. Yes. Fits into either of the HC's expansion ports. Yes Not CE marked configuration - version 2 model required FCC Class B, CE-mark and E-marknot CE marked for use with HC Docking Station EN60950 9 way miniDIN female. Standard Centronics 25 way D female 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600. 5, 6, 7, 8 (ASCID). 1,2 Odd, even, none. XON/XOFF, RTS/CTS, DSR/DTR, DCD. Via DSR line (optional). Psion proprietary MCLINK protocol. Xmodem protocol. APPENDIX A TECHNICAL SPECIFICATIONS RS232 interface Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board link. RS232 , (9 way male D-type), pinout Pin 1: DCD input. Pin 2: RX input. Pin 3: TX output. Pin 4: DTR output. Pin 5: Ground (OV). Pin 6: DSR input. Pin 7: RTS output. Pin 8: CTS input. Pin 9: Optional VSUP input/output, (7-10V DC). DC input must not exceed 10V. Parallel Interface Parallel Interface pinout Pin | Strobe output Pin 2 Data 0 output Pin 3 Data 1 output Pin 4 Data 2 output Pin 5 Data 3 output Pin 6 Data 4 output Pin 7 Data 5 output Pin 8 Data 6 output Pin 9 Data 7 output Pin 10 ACK input Pin 11 BUSY input Pin 12 PE input Pin 13 NC Pin 14 AUTO FD XT output Pin 15 ERROR input Pin 16 INIT output Pin 17 SLCT IN output Pins 18-25 Ground 0V Psion HC RS232/Parallel (printer) module, version 2 Technical Specification Important Notice - Compatibility This module must be used in the HC Docking Station for countries requiring the CE Mark. This module is compatible with all configurations of Psion HC, HC Docking Station and Workabout Docking Station and is recommended for all new installations. HC PROGRAMMING GUIDE Physical Part number: Module: HC compatibility HC-DOS compatibility 1502 0052 10 Integrated removable module. Yes. Fits into either of the HC's expansion ports. Yes Docking station compatibility Yes EMC: Safety: Connectors RS232: Parallel: Serial Interface Baud: Data bits: Stop bits: Parity: Handshaking: Remote switch-on Protocols: RS232 interface FCC Class B, CE-mark and E-mark EN60950 9 way male D-type (RS232, PC AT type). 15 way High Density D male. A 15 Way to 25 Way converter cable is required for connection to a standard Centronics port. 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600. 5, 6, 7, 8 (ASCID). 1,2 Odd, even, none. XON/XOFF, RTS/CTS, DSR/DTR, DCD. Via DSR line (optional). Psion proprietary MCLINK protocol. Xmodem protocol. alin) MC EXPANSION MODULI PARALLEL / SERIAL PORTS MADE INTHE UK PRINTER & PARALLEL PORT AS 232 SERIAL Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board link. RS232 , (9 way male D-type), pinout Pin |: Pin 2: Pin 3: Pin 4: Pin 5: Pin 6: Pin 7: Pin 8: Pin 9: DCD input. RX input. TX output. DTR output. Ground (OV). DSR input. RTS output. CTS input. Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. APPENDIX A TECHNICAL SPECIFICATIONS 15 way High Density Parallel Interface 15 way High Density Parallel socket (male) 15 way High Density Parallel Interface pinout Pin | Pin 2 Pin 3 Pin 4 Pin 5 Pin 6 Pin 7 Pin 8 Pin 9 Pin 10 Pin 11 Pin 12 Pin 13 Pin 14 Pin 15 Strobe output Data 0 output Data 1 output Data 2 output Data 3 output Data 4 output Data 5 output Data 6 output BUSY input ERROR input INIT output SLCT IN output Data 7 output PE input Ground 0V Psion 15 Way to 25 Way converter cable Technical Specification Physical Part number: Length: EMC: Safety: Connectors 15-way parallel: 25-way parallel: 2403 0026 01 30cm. FCC Class B, CE-mark and E-mark EN60950 female; for connection to the 15-way high-density parallel (printer) socket on the Psion HC RS232/Parallel (printer) module, version 2 for connection to a standard Centronics port on a printer. HC PROGRAMMING GUIDE 15 way High Density Parallel plug (female) 15 way High Density Parallel Interface connector pinout Pin | Strobe output Pin 2 Data 0 output Pin 3 Data 1 output Pin 4 Data 2 output Pin 5 Data 3 output Pin 6 Data 4 output Pin 7 Data 5 output Pin 8 Data 6 output Pin 9 BUSY input Pin 10 ERROR input Pin 11 INIT output Pin 12 SLCT IN output Pin 13 Data 7 output Pin 14 PE input Pin 15 Ground 0V 25-way connector pinout Pin | Strobe output Pin 2 Data 0 output Pin 3 Data 1 output Pin 4 Data 2 output Pin 5 Data 3 output Pin 6 Data 4 output Pin 7 Data 5 output Pin 8 Data 6 output Pin 9 Data 7 output Pin 10 NC Pin 11 BUSY input Pin 12 PE input Pin 13 NC Pin 14 NC Pin 15 ERROR input Pin 16 INIT output Pin 17 SLCT IN output Pins 18-25 Ground 0V APPENDIX A TECHNICAL SPECIFICATIONS Psion HC MCR /RS232 /TTL RS232 module, (Version 2), Technical Specification Physical Part number: Module: HC compatibility HC-DOS compatibility 1502-0003 Integrated removable module. Yes. Fits into either of the HC's expansion ports. No Docking station compatibility Yes Certification: MCR Interface Connections Socket: Readers supported: MCR unit power supply: Pinout Plug required: Pin 1: Pin 2: Pin 3: Pin 4: Pin 5: Pin 6: Pin 7: FCC Class B VDE Class B 7 way locking miniDIN female. Single or simultaneous two track reader. 5V DC output available to power MCR unit. This is software switchable. Hosiden type TCP6170-1100 or equivalent. SV output (100mA max). CLD. Card load input (low when card in reader). 100k pullup to 5V. DATALIL. Data input for track | reader. Data is read in on falling edge of the clock line. 100k pullup to 5V. CLOCK 1. Clock input for track 1 reader. 100k pullup to 5V. DATA2. Data input for track 2 reader. Data is read in on falling edge of the clock line. 100k pullup to 5V. CLOCK2. Clock input for track 2 reader. 100k pullup to 5V. Ground. (OV). RS232 / RS232 TTL Interface Connections The single RS232 interface can be software switched between 2 sockets. Sockets: Interface Baud: Data bits: Stop bits: Parity: Handshaking: Remote switch-on Protocols: 8 way locking miniDIN socket (RS232 TTL). 9 way miniDIN socket (standard RS232). 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600. 5, 6, 7, 8 (ASCID). 1.2. Odd, even, none. XON/XOFF, RTS/CTS, DSR/DTR, CDC. via DSR line (optional). Psion proprietary MCLINK protocol. Xmodem protocol. HC PROGRAMMING GUIDE RS232 TTL socket TTL levels: 0-5V. TTL signals: TX, RX, RTS, CTS, DSR., plus software switchable unregulated 7-10V DC and regulated SV DC. TTL polarity: Programmable in software. Readers supported: This interface is intended for use with peripherals such as low power laser and CCD bar code scanners which support a TTL level RS232 interface. Scanner power supply: Unregulated 7-10V DC and regulated 5V DC to power the scanner. These are software switchable. RS232 TTL socket pinout Plug required: Hosiden type TCP6180-1100 or equivalent. Pin 1: 5V DC regulated output. (250mA max*). Pin 2: TX output. TTL transmit. Pin 3: RTS output. TTL handshaking. Pin 4: VSUP output. Unregulated 7-10V DC output (250mA max*). Pin 5: RX input. TTL receive. Pin 6: CTS input. TTL handshaking. Pin 7: DSR input. TTL handshaking. Pin 8: Ground. (OV). *The maximum combined current must not exceed 250mA Standard RS232 interface Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board link. RS232 , (9 way male D-type), pinout Pin 1: DCD input. Pin 2: RX input. Pin 3: TX output. Pin 4: DTR output. Pin 5: Ground (OV). Pin 6: DSR input. Pin 7: RTS output. Pin 8: CTS input. Pin 9: Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. Psion HC RS232 /TTL RS232 module, Technical Specification Note: a 16550 RS232/TTL-RS232 module is also available and is described later in this Appendix. Physical Part number (IP64): 1502-0039 Part number (non-IP64): 1502-0040 Module: Integrated removable module. HC compatibility Yes. Fits into either of the HC's expansion ports. HC-DOS compatibility Yes Docking station compatibility Yes EMC: Safety Weatherproofing: Connections APPENDIX A TECHNICAL SPECIFICATIONS FCC Class B, CE-mark and E-mark EN60950 IP64 (depending on model, see part number above) The single RS232 interface can be software switched between 2 sockets. Sockets: Peripherals supported: RS232 interface Baud: Data bits: Stop bits: Parity: Handshaking: Remote switch-on Protocols: RS232 TTL interface TTL levels: TTL signals: TTL polarity: Power supply outputs: Power supply inputs: RS232 interface 9 way female D-type 9 way male D-type (RS232 TTL). (RS232, PC AT type). The TTL RS232 interface is intended for use with peripherals such as low power laser and CCD bar code scanners which support a TTL level interface. 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600. 5, 6, 7, 8 (ASCII). 1, 2. Odd, even, none. XON/XOFF, RTS/CTS, DSR/DTR, CDC. via DSR line (optional). Psion proprietary MCLINK protocol. Xmodem protocol. 0-5V. TX, RX, RTS, CTS, DSR., plus software switchable. Programmable in software. Software switchable unregulated 7-10V DC, unswitched unregulated 7-10V DC and regulated SV DC. The unswitched 7-10V pin is directly connected to the HC main power rail and can therefore be used to power the HC. To do this the supply coming into the HC must be diode isolated (so as not to take power from the HC) and in the range 7-10V (1OV maximum). NOTE: powering the HC from this pin will not charge the HC internal battery. Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin is not implemented. This pin on the HC can be optionally connected to the HC VSUP input/output supply via an on board link. This is described above. RS232 , (9 way male D-type), pinout Pin |: Pin 2: Pin 3: Pin 4: Pin 5: Pin 6: Pin 7: Pin 8: Pin 9: DCD input. RX input. TX output. DTR output. Ground (OV). DSR input. RTS output. CTS input. Optional VSUP Input/output, (7-10V DC). DC input must not exceed 10V. HC PROGRAMMING GUIDE RS232 TTL interface RS232 TTL socket pinout Pin |: Pin 2: Pin 3: Pin 4: Pin 5: Pin 6: Pin 7: Pin 8: Pin 9: VSUP switched output. Unregulated 7-10V DC output (250mA max*). RX input. TTL receive. TX output. TTL transmit. SV output. (250mA max*). Ground (OV). DSR input. TTL handshaking. RTS output. TTL handshaking. CTS input. TTL handshaking. VSUP Input/output. 7-10V DC input/output. DC input must not exceed 10V. *The maximum combined current must not exceed 250mA Psion HC 16550 RS232 /TTL-RS232 module, Technical Specification Note: an ASICS based RS232/TTL-RS232 module is also available, and is described above. This module may be used with any standard HC (or HCDOS machine) for faster data transfer rates than the standard module. The essential difference between this module and the standard "RS232 / TTL-RS232" module is that a 16550 UART is used rather than the ASIC5 UART used in the standard module. Also the RI (Ringing Indicator) function is provided to make it a true IBM PC-AT RS232 interface (note that the HC software does not make any use of RI ). Physical Part number Module: Operating temperature Storage temperature Weight HC compatibility HCDOS compatibility 1502-0045 Integrated removable module. Fits into either of the HC's expansion ports. -20 to +60 °C -20 to +60 °C 60g Yes, loadable PDD required Yes Docking Station compatibility No Emissions Connections FCC class A The single RS232 interface can be software switched between 2 sockets. Sockets: Peripherals supported: 9 way female D-type (RS232 TTL). 9 way male D-type (RS232, PC AT type; full EIA-232 signal levels). The TTL RS232 interface is intended for use with peripherals such as low power laser and CCD bar code scanners which support a TTL level RS232 interface. The polarity of this interface can also be programmed to be standard (non-inverting) or inverting. APPENDIX A TECHNICAL SPECIFICATIONS RS232 interface Baud: 50, 75, 11, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600, 19200; also 38400 using error corrected transmission. Data bits: 5, 6, 7, 8 (ASCII). Stop bits: 1, 2. Parity: Odd, even, none. Handshaking: Xon/Xoff, RTS/CTS, DSR/DTR, CDC. Remote switch-on via DSR line (optional). Protocols: Psion proprietary MCLINK protocol. Xmodem protocol. RS232 TTL interface TTL levels: 0-5V. TTL signals: TX, RX, RTS, CTS, DSR., plus software switchable. TTL polarity: Programmable in software. Power supply outputs: Software switchable unregulated 6-10V DC, unswitched unregulated 6-10V DC and switched regulated 5V DC. Power supply inputs: The unswitched 7-10V pin is directly connected to the HC main power rail and can therefore be used to power the HC. To do this the supply coming into the HC must be diode isolated (so as not to take power from the HC) and in the range 7-10V (OV maximum). NOTE: powering the HC from this pin will not charge the HC internal battery. HC usage A loadable software Physical Device Driver (PDD) is available to allow this module to be used on any standard HC. Once this driver is loaded the module is accessed exactly the same as the current ASICS based RS232/TTL-RS232 module. When fitted it allows the HC to reliably communicate at 19200 baud (the standard module is only reliable up to 9600 baud). However when using error corrected protocols such as LINK, communicating at 38400 baud is feasible. In tests file transfer rates in excess of 2Kbytes/second have been achieved using LINK in conjunction with MCLINK on a 486 PC. Docking station usage The HC/HCDOS communicates with this module via the parallel expansion bus, therefore it cannot be plugged into a Docking Station. HCDOS usage Baud rates of up to 115,200 are achievable compared with a maximum of 19,200 for the standard module. Connector selection and TTL polarity selection will normally be under application control but the HCSETUP utility can be used. The port appears as COM1 if the module is plugged into the top HCDOS expansion slot or COM2 in the bottom slot. RS232 interface Provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin can be optionally connected to the HC VSUP input/output supply via an on board switch. This is described below. RS232 , (9 way male D-type), pinout Pin I: DCD input. Pin 2: RX input. Pin 3: TX output. Pin 4: DTR output. Pin 5: Ground (OV). Pin 6: DSR input. HC PROGRAMMING GUIDE Pin 7: RTS output. Pin 8: CTS input. Pin 9: RI input or VSUP Input. 7-10V DC input. DC input must not exceed 10V. or VSUP Output. 6-10V DC unregulated. 250mA maximum current, or 200mA maximum current if another expansion module is also being powered. See below for full details. Pin 9 RI / VSUP switch If you hold the module with the component side of the PCB facing you and the D-type connectors at the top, this switch is located below the right hand D-type connector. Important: the normal position for this switch is 'RI' (in the left hand position), it should only be switched to the 'VSUP' position for special applications as described below otherwise damage could occur to either the HC or the device connected at the other end. The 'VSUP’ connection should be selected only if one of the following is required: 1. The HC is to be powered externally. The supply applied to the HC must be diode isolated (to prevent power drain from the HC) and in the range 7-10V (1OV maximum). NOTE: powering the HC from this pin will not charge the HC internal battery. 2. The HC is required to supply power to another device, for example certain true RS232 I/F laser scanners require power to be supplied from the RS232 connector. Note that VSUP is not software switchable and is present even when the HC is switched off, so the device would need its own ON-OFF switch to prevent the HC battery being drained when the device is not in use. VSUP is an unregulated supply in the range 6-10V. The device powered from pin 9 should not draw more than 250mA from VSUP if no other expansion modules are powered up simultaneously (if another expansion module is fitted and powered up, the current drawn should not exceed 200mA). DSR auto-wakeup switch If you hold the module with the component side of the PCB facing you and the D-type connectors at the top, this switch is located to the bottom left hand corner of the PCB. If this switch is ON (in the right hand position) the HC is automatically turned on when DSR is asserted by the device connected to the RS232 port. Power consumption When the RS232 port is open it typically draws 8mA plus the current drawn by the device connected at the other end, this will vary depending on the device, for example connected to a PC the total current drawn will increase to typically 18mA (this however will vary from one PC to another). TTL interface RS232 TTL socket pinout, (9 way female D-type) Pin 1: VSUP switched output. Unregulated 6-10V DC output (250mA max*). Pin 2: RX input. TTL receive. Pin 3: TX output. TTL transmit. Pin 4: Switched 5V output. (250mA max*). Pin 5: Ground (OV). Pin 6: DSR input. TTL handshaking. Pin 7: RTS output. TTL handshaking. Pin 8: CTS input. TTL handshaking. Pin 9: VSUP Input. 7-10V DC input. DC input must not exceed 10V. or VSUP Output. 6-10V DC unregulated. 250mA maximum current*, or 200mA maximum current* if another expansion module is also being powered. *The maximum combined current must not exceed 250mA A-14 APPENDIX A TECHNICAL SPECIFICATIONS Switched VSUP (pin 1) and 5V (pin 4) outputs Both these switched power supply outputs are provided to power peripherals plugged into the TTL connector and both are enabled only when the port is open and TTL connector is selected. VSUP is an unregulated supply in the range 6-10V. The 5V regulated output has a tolerance of +/- 5%. The device powered from either supply should not draw more than 250mA if no other expansion modules are powered up simultaneously (if another expansion module is fitted and powered up, the current drawn should not exceed 200mA). If current is drawn from both rails then the combined current should not exceed 250mA (or 200mA if another module is present). VSUP direct connection (pin 9) A direct VSUP connection is also provided for the same purposes as the VSUP option on pin 9 of the RS232 connector, see description above. Power consumption When the port is open and the TTL interface is selected, the interface typically draws 5mA. In most cases however the current drawn by the peripheral device dominates. Psion HC Bar Code Reader module, (Version 2), Technical Specification Physical Part number (HP wand): 1502-0020 Part no. (Welch Allen wand): 1502-0021 Module: Integrated removable module. HC compatibility Yes. Fits into either of the HC's expansion ports. HC-DOS compatibility No Docking station compatibility No Certification: FCC Class A VDE Class B Connection Socket: 6 way locking miniDIN socket. Peripherals supported: Will support most standard bar code wands and also scanners with wand emulation output. It is supplied with one of either: HP wand HPBCS-A207 and plug or Welch Allen wand and plug Remote switch-on: Facility for remotely switching machine on with bar code wand or scanner. Power supply output: 5V DC available to power a wand or scanner. This is software switchable. Pinout Plug required: Hosiden type TCP6160-1100 or equivalent. Pin 1: EXON. Turns HC on when pulled low. 100k pullup to 5V present at all times (even if machine is switched off) Pin 2: Enable output. Optional output to barcode device. Under software control (application dependant). Pin 3 Switch input. Optional input for barcode switch. Pin 4: Data input. Input from barcode wand. 2k2 pullup to 5V when reading from wand. Pin 5: SV output. (Max 250mA) Pin 6: Ground. (OV) HC PROGRAMMING GUIDE Psion HC RS232 / Bar Code Reader module, Technical Specification This module combines a standard RS232 interface via a 9 way male D-type (PC-AT type) connector with a bar code interface via a 9 way male D-type click-lock connector. Physical Part number 1502-0044 Module: Integrated removable module. Operating temperature: -20 to +60 °C Storage temperature: -20 to +60 °C Weight: 62g HC compatibility Yes. Fits into either of the HC's expansion ports. HC-DOS compatibility Yes Docking station compatibility Yes EMC: FCC Class B, CE-mark and E-mark Safety EN60950 Weatherproofing: No RS232 interface The RS232 interface is accessed by opening TTY:A (top slot) or TTY:B (bottom slot). It provides standard RS232 level signals and is similar to the RS232 interface on an IBM AT. The difference between this socket and an IBM AT is that the RI (ringing indicator) pin (pin9) is not implemented. This pin can be optionally connected to the HC VSUP main power supply rail by fitting a jumper to the 2-pin header on the PCB (described below). Connection Socket: 9 way male D-type (PC-AT type) Peripherals supported: Will support most standard bar code wands and also scanners with wand emulation output. Remote switch-on: Facility for remotely switching machine on. Selectable by switch on PCB; see below. Power supply input: Optional VSUP connection, (7-10V DC unregulated), to power the HC; see below. Power supply output: Optional VSUP connection, (6-10V DC unregulated), available to power a wand or scanner; see below. Pinout Pin 1: DCD input Pin 2: RX input. Pin 3: TX output. Pin 4: DTR output. Pin 5: Ground (Ov) Pin 6: DSR input. Pin 7: RTS output. Pin 8: CTS input. Pin 9: Optional VSUP connection. See below. APPENDIX A TECHNICAL SPECIFICATIONS Pin 9 VSUP connection The jumper should be fitted to make this connection only if one of the following is required: e The HC is to be powered externally. The supply applied to the HC must be diode isolated (to prevent power drain from the HC) and in the range 7-10V (10V maximum). NOTE: powering the HC from this pin will not charge the HC internal battery. e The HC is required to supply power to another device, for example certain true RS232 I/F laser scanners require power to be supplied from the RS232 connector. Note that VSUP is not software switchable and is present even when the HC is switched off, so the device would need its own ON-OFF switch to prevent the HC battery being drained when the device is not in use. VSUP is an unregulated supply in the range 6-10V. The device powered from pin 9 should not draw more than 250mA from VSUP if no other expansion modules are powered up simultaneously. If another expansion module is fitted and powered up, the current drawn should not exceed 200mA. Warning: the jumper should not be fitted in any other circumstance, to prevent damage to the device connected or to the HC. DSR auto-wakeup switch If you hold the module with the component side of the PCB facing you and the D-type connectors at the top, the switch is located to the bottom left hand corner of the PCB. If this switch is ON (in the left hand position) the HC is automatically turned on when DSR is asserted by the device connected to the RS232 port. Power consumption The RS232 port is only powered up when the appropriate channel is open. Typically the interface draws 10mA plus the current drawn by the device connected at the other end, this will vary depending on the device, for example connected to a PC the total current drawn will increase to about 20mA (this however will vary from one PC to another). Bar code interface The interface to the Bar code decoder is via RS232 serial signals. It is accessed by opening TTY:D(top slot) or TTY:E (bottom slot). The port is powered up and down by opening and closing the appropriate channel. Decoder Decoder IC: Input speed: Hewlett Packard HBCR-1612 9600 Baud via serial Input data: Discrimination: Supported symbologies: Maximum scan speed: Output data: Peripherals supported: Unsupported scanners: Programming: 8 Data bits, 1 Stop Bit Automatic Code 39 (standard or extended) Interleaved 2 of 5 UPC A, EO, E1 (with supplemental digits) EAN/JAN 8,13 (with supplemental digits) Codabar Code 128 30 ips (76 cm/s) By default when a successful bar code is read the number is transmitted to the HC in ASCII format followed by a carriage return. Will support most standard bar code wands and also scanners with wand emulation output. "Undecoded Laser Scanner' ( also known as HHLC, hand held laser compatibility). The HBCR-1612 is programmable via escape sequences. For more detailed programming information refer to the //O Devices Reference manual. HC PROGRAMMING GUIDE Connection Socket: 9 way male D-type click-lock Power supply outputs: VSUP connection, (6-10V DC unregulated), and 5V DC regulated, available to power a wand or scanner. See below. Pinout Pin 1: DCD input Pin 2: Bar Data input Pin 3: No connect Pin 4: Switched VSUP (6-10V DC) output*. Pin 5: DSR input Pin 6: DTR output. Pin 7: Ground (OV) Pin 8: Ground (OV) Pin 9: Switched 5V regulated output*. VSUP and 5V regulated outputs Both these switched power supply outputs are provided to power devices plugged into the bar code port and both are enabled only when the appropriate channel is open. VSUP is an unregulated supply in the range 6-10V. The 5V regulated output has a tolerance of +/- 5%. *The device powered from either supply should not draw more than 250mA if no other expansion modules are powered up simultaneously. If another expansion module is fitted and powered up, the current drawn should not exceed 200mA. If current is drawn from both rails then the combined current should not exceed 250mA (or 200mA if another module is present). Power consumption The Bar code port is only powered up when the appropriate channel is open. Typically the interface draws 10mA idle plus any current drawn by the wand. During a scan the interface typically draws 24mA plus the current drawn by the wand. Current drain varies greatly from one wand to another and choice of wand can have a considerable effect on battery life. Note HC bar code readers may be converted for use with the Psion Workabout. See Appendix A - Technical Specifications in the Workabout Programming Guide manual. Psion HC Modem UK module, Technical Specification Physical Part number: 2400-0090-01 Module: Integrated removable module. HC compatibility Yes. Fits into either of the HC's expansion ports. HC-DOS compatibility No Docking station compatibility Yes Certification: BABT approved in UK (approval number NS/1397/3/T/605 141) BS6301 (safety) Power: 70mA maximum Environment Operating temperature: Operating humidity: Communication modes V standards: Operational modes: Data transfer rate: Network connection Line connection: Signal level: Equalisation: Interface: REN: Autodial/autoanswer Dial method: Call progress: Call control: Auto answer: Mode selection: Call disconnection: Data interface DTE interface: Command buffer: Protocol: DTE speed: Error correction: Diagnostics Test modes: APPENDIX A TECHNICAL SPECIFICATIONS 0 - 50C 0 - 96% non-condensing V21, V22, V22bis, V23. V22bis 2400 bps full duplex. V22 1200 bps full duplex. V23 1200/75 bps full duplex. V23 75/1200 bps full duplex. V21 300 bps full duplex. Up to 2400 bps with V22bis. BT 600 series jack for 2 wire PSTN, 3 wire bell tinkle suppression supported -9dBm. Transmit - fixed compromise, receive - automatic adaptive. 600Q 1 Pulse and tone dialling. Internal loudspeaker with volume control, extended results codes. Extended Hayes AT command set. To ITU-T (CCITT) V25 recommendation, with echo suppression. Automatic configuration to V23/V22bis/V22/V21 on receive. Loss of carrier, DTR or by command. Psion high speed serial Compliant with V24/V28 TX, RX, RTS, CTS, DSR, DCD, DTR, RI 40 characters Async command and data mode. 300, 600, 1200 and 2400bps. V42 including LAPM and MNP Class 4. V54 digital and analogue loops. Psion HC Vehicle Interface Box Technical Specification This unit is designed to be mounted in a vehicle and provide the following functions: e DC power regulation and protection. e §6°=Wiring interfacing. e Direct connection to the RS232 interface. The unit and cables have E-Mark certification. The wiring connections, (as shown in the system block diagram below), are: e Unregulated 10-18 volts input from the vehicle source, (‘Vehicle Supply’). e RS232 serial interface to a radio or telephone modem, ('RS232'). e RS232 to/from the HC, power, trickle charge for the battery, ((RS232 and Power’). Note that the HC Vehicle Interface Box does not support the Psion Workabout range; see Appendix A in the Workabout Programming Guide manual for a description of the Workabout VIC (Vehicle Interface Cradle). The HC needs to be fitted with a special LIF-PFS/TTL-RS232 expansion module. HC PROGRAMMING GUIDE ooo === O00000) OO0000) Vehicle Supply oOo00o00 DOoo000 poo50 —— Bonn” RS 232 ry iJ and Power 5 1 RS 232 2 O° ,— l oo 0 HC Computer Vehicle Interface Box Radio/Modem System block diagram LED Indicator 9 Way D type (Male) connector 15 Way D type (Female) connector and 2 way Power input End views of the HC Vehicle Interface Box showing the connectors The Vehicle Interface kit includes: e Vehicle Interface Box, Part Number 2400-0079. e =A LIF - RS232 cable 1.5m length, terminated at one end with a LIF connector (Polarisation Type A) and a 15 way D type connector at the other. LIF - RS232 Cable : Part Number 2403-0011 e The appropriate HC Expansion Module, TTL/LIF-RS232. Part Number 2400-0068 Vehicle Interface Box Installation Kit Psion HC Cradle Technical Specification Note: this HC accessory has been superseded by the Psion HC Docking Station. Dimensions Size: 190mm (length) x 150mm (width) x 850mm (height) Weight: 400g HC compatibility Yes. Models prior to revision 4 (serial number below 200,000). HC-DOS compatibility No Interfaces HC serial interface: High speed - 190kBytes/sec Expansion module slot: Fits RS232/Parallel and Modem modules APPENDIX A TECHNICAL SPECIFICATIONS Battery recharge Trickle charge: 14-16 hour recharge of HC battery in situ NiCad recharge slot: Allows charging of stand alone spare battery Features Security lock: Ensures HC held in position Insertion/removal: Trigger loaded spring release and hand recess Control panel: LEDs indicating mains power, fast charge, spare battery charge, active comms Mounting options Flat surface: e.g. point-of-sale counter Wall mounting: e.g. industrial environments In-vehicle: e.g. fleet vehicles Psion's continuing product development and improvement programs mean that specifications and features are subject to change at any time and without notice. Psion HC Docking Station Technical Specification Introduction The HC Docking Station is designed to provide a multi-function mounting point for the Psion HC and the Psion HC-DOS corporate hand held computers, (referred to in this technical specification as the computer). The Docking Station supersedes the HC Cradle, and has the following features: e Battery management, including fast charge of batteries (fast model) e Small footprint e Reliable connection between the Psion and the docking station using the new LIF connector ¢ Option for in-vehicle use e FCC, static and safety approval Compatibility with Psion HC and RWAN machines Compatibility with the Psion HC To allow connection of the HC to the Docking Station using the LIF connector, the HC main circuit board was revised so that the connections for the fast serial and charging interfaces were available at the bottom expansion slot (version 4 onwards). As a result of this, Psion HC computers with pre revision 4 boards (serial numbers below 200,000) are not compatible with the Docking Station or expansion modules which have a LIF interface. The HC must also be reproed to version 1.70F or above of the EPOC operating system. A spares kit is available consisting of an HC main board (latest revision), plus the side and bottom boards. This allows a field update so that early versions can be made compatible with the Docking Station. Contact your Psion distributor for more information. Only HC battery packs marked "Fast Rechargeable" and with the letters "FC" (for Fast Charge) in the top right hand corner of the label are suitable for fast charging with the HC docking station. Compatibility with RWAN/PDT220 The Docking Station does not support RWAN/PDT220 machines. Variants A total of four build options available for the HC: 1. HC fast charge HC PROGRAMMING GUIDE 2. HC trickle charge, Note: Both the above variants are also available with vehicle support circuitry on board. This gives a total of 4 possible build variants. Identification PCB number and revision marked on PCB is common for all variants. The main visual differences that distinguish an HC fast charger from a Workabout fast charger are: HC fast charger: 4 pin bulky power supply socket fitted Workabout fast charger: 2 pin 1.3mm DC jack fitted Docking Station Unit Main features The Docking Station Unit has the following features: e = Fast charging of the computer internal battery pack, (fast model). e Spare battery pack fast charging. e Stable desktop mounting. e Accepts some of the HC expansion modules which communicate via the Psion Fast Serial (PFS) protocol. These are accessible by the HC and HC-DOS computers. See the table Psion HC build variant and accessories matrix at the end of this Appendix for details. e Data transfer from the computer, (with the appropriate expansion module and software driver). e Simultaneous battery charging and data transfer, (if the Psion is not monitoring battery status). e Wall mounting and bulk head fitting designed in. e The battery compartment is factory configured to accept as standard the HC rechargeable battery pack. Status indicators There are several LEDs on the front of the charger unit to indicate the following: e¢ Communications/data transfer e §=©Yellow during data transfer e Power status-On/Off ¢ Green when charger is connected to mains power e Main computer battery charging status (Fast model only, see Battery Status LED conditions) e Spare battery charging status (Fast model only, see Battery Status LED conditions) Battery charging The Docking Station has two charging modes: e = Normal e Software controlled. See the Cradle and Docking Station chapter in the I/O Devices Reference manual. If both the computer and the spare battery are fitted when the docking station is connected to mains power, charging priority will go to the spare battery. If the docking station is already connected to mains power , charging priority will go to whichever battery was plugged in first. The computer main battery can be discharged before charging commences. This feature is controlled from the computer. Note that the Slow Charge variant of the Docking station does not have a Battery Status LED. This is because it has only one status - charging. APPENDIX A TECHNICAL SPECIFICATIONS Battery Status LED conditions LED indication Battery status Flashing red Preparation for fast charging (two seconds) or Battery condition outside specified range - trickle charging or For the battery pack inside the Psion: discharging under software control or Error Steady red Charging Steady green Charged Flashing red/green Waiting or For the battery pack inside the Psion: discharging under software control, while the spare is fast charging Charging both battery packs If a spare battery is inserted into the Docking Station whilst a battery pack inside the Psion is being charged, charging of the spare pack will begin after the internal battery pack has been charged. If a Psion computer is inserted into the Docking Station whilst a spare battery pack is being charged, charging of the battery inside the Psion will begin after the spare pack has been charged. If both the Psion and the spare battery pack are inserted into the Docking Station at the same time, (or both are in the Docking Station prior to it being connected to the mains), the packs will not be charged simultaneously. In the case of the Fast Charge variant of the Docking Station their respective LEDs will flash red for about two seconds, until the charger decides which to battery pack to charge. The LED for the one charging then comes on red, and the other one's LED starts flashing red/green as it is waiting to be charged. For both Docking station variants the spare battery pack will normally be charged first. Battery Fast Charging conditions The Fast Charge variant of the Docking Station can Fast Charge in the following conditions: Within the temperature range: 5 to 45 °C Voltage of the battery pack: 4.5 to 11.3V DC for the HC and HC-DOS If the battery pack temperature or voltage is outside the specified range, the charger trickle charges until the condition is within the allowable range, after which it will fast charge. A new or fully discharged battery pack (that has been left on for a long time) may have a voltage below the minimum for Fast Charging. If the battery temperature is within the allowable range and the battery status LED continues to flash red it is likely that the battery pack is faulty. Discharging prior to charging & capacity measurement The Psion's internal battery pack may be discharged, under software control, prior to charging. This is not possible with the spare battery pack. It is possible to charge the spare battery pack whilst discharging the main battery pack in the Psion. Software controlled discharging of the battery pack leaves the voltage above the allowable minimum for subsequent Fast Charging. Charging will automatically commence after the battery is discharged. Under software control it is also possible to measure the actual capacity or the remaining capacity of the battery pack inside the Psion computer. the discharging current for the HC is 300mA + 5%. Fast Charging times A fully discharged battery pack takes approximately one hour to Fast Charge to 90-95% of its maximum capacity. If left in the Docking Station after this time it will be "topped-up" to its maximum capacity after a further two hours. HC PROGRAMMING GUIDE Slow Charging times A fully discharged battery pack takes approximately 14 to 16 hours to Slow Charge to 100% of its maximum capacity. Charging limitations The Fast Charge and Slow Charge facilities only support the main Computer battery, not the battery of any attached peripheral. The HC Printer however, contains its own Quick Charge circuitry and may charge simultaneously under software control. LIF Mounting Kit The LIF mounting kit allows a LIF connector on the end of a cable to be fitted to a holster. The holster itself is a plastic moulding into which the computer can be inserted. This incorporates a positive latching mechanism which holds the computer securely in place. The holster does not include any electronics. The Clip cover and the 2 short screws that are fitted as standard to the LIF connector will need to be replaced with the blank cover and the 2 long screws supplied with the kit. HC/HC-DOS Holster with Socket Housing The kit for the HC Computer consists of:- e HC holster e LiF connector rear housing e LIF connector blank front cover e 2screws - type K2.2 x 12 mm CSK ( not shown) HC Docking Station This is a Battery Charger with serial data communication capabilities supplied with a factory fitted HC holster, also known as an HC Docking Station. It comes in two variants, Fast Charge and Slow Charge. The cable from the hardware board to the LIF connector is protected by an over-moulded rubber grommet. The HC Docking Station is also compatible with the HC-DOS computer. A 12v 2 amp unregulated power supply is available separately. APPENDIX A TECHNICAL SPECIFICATIONS HC Docking Station: Part Numbers 1503-0017-01 (Fast Charge) 1503-0018-01 (Slow Charge) 12V 2 amp unregulated Power Supply Note: Euro part number 2300-0212-01, US part number 2300-0213-01; a universal switch mode adaptor is also available, part number 2402-0003-01 (contact your Psion distributor for details). HC PROGRAMMING GUIDE Psion LIF - RS232 Cable Technical Specification A cable 1.5 m length terminated at one end with a LIF connector (Polarisation Type A) and a 15 way D type (Male) plug at the other. LIF - RS232 Cable . APPENDIX A TECHNICAL SPECIFICATIONS Psion LIF Connector Technical Specification The Low Insertion Force (LIF) connector has been designed for connecting the computer to the Docking Station, as well as to other Psion accessories. The LIF connector cover is moulded with a polarising pin in one of two positions. Pin numbers tot | GROUND 9 2,3,4,5,8,10 1,6,7,11 2nd L_______} SIGNALS 3rd Cl] POWER The step arrangement of the LIF Connector pins Cable mounted LIF (Female plug) Computer mounted LIF (Male socket) Cable mounted LIF (Female plug) Computer mounted LIF (Male socket) The Type A and Type B polarisation of the LIF Connector HC PROGRAMMING GUIDE Pin Definition for LIF - PFS Connector LIF Connector Polarisation Type B Wire Colour Contact Direction Standard Function Docking Station usage Gauge (Docking Station's perspective) 7/0.1 Brown Third Input Local! Computer Active. Used as an enable for High when the computer is the Docking Station on. (The Workabout can resident expansion source 100mA from this pin module 5V supply. and the HC/HC-DOS 5mA to power remote* circuitry) EXON 7/0.1 Blue Second Output EXternal switch ON, active May be asserted by a high (+5V). Asserted by a Docking Station resident remote device to switch on expansion module. the computer. 7/0.1 Orange Second Output INTerrupt to computer, May be asserted by a active high (+5V). Docking Station resident expansion module. THM 7/0.1 Yellow Second Input Battery thermistor terminal. Standard function Allows remote* sensing of the battery temperature. DLA 7/0.1 Green Second Output Disconnect Local? ASIC, Asserted by the Docking active high (+5V). (does not Station ASIC, connects apply to Workabout). When the Docking Station this signal is asserted the resident expansion serial channel is module to the serial disconnected from the local? channel. ASIC4/5 in the HC resident expansion module (if present) and instead connected to a remote ASIC4/5 (if present). BAT 28 Third Output +ve battery terminal (1 amp) Standard function SWG 7 Vin 28 Black Third Output Power supply to computer Standard function SWG (+10V) SCLK 7/0.1 Serial channel CLocK. Standard function White First Power, signal ground and - Standard function ve battery terminal (1 amp) SDATA | 7/0.1 Bi-directional | Serial channel DATA. Standard function STATUS| = 7/0.1 Pink Third Output STATUS. Connected to a Driven low by an open pull-up resistor to allow collector driver when connection to an open- LCA is high and the collector/drain driver. Normal Docking Station is usage is: low indicates the powered-up to allow the presence of a remote computer to sense device. whether or not the Docking Station is connected. APPENDIX A TECHNICAL SPECIFICATIONS Pin Definition for LIF - RS232 Connector LIF Connector Polarisation Type A Wire Colour Contact Direction Gauge (Computer's perspective) 4 THERM | 7/0.1 eee ac Battery thermistor terminal VBAT cD RX TX DTR me |] — VIN 8 DSR ND RTS CTS 2 D G 7 Black Third Input Power supply to computer G G G 2 SW 2 SW 2 Ww peo fy cee S) 10 Definitions Computer HC, HC-DOS or Workabout Docking Station Expansion module fitted to the Docking Station, may or may not be present. resident expansion module HC resident Expansion module fitted to the HC which contains the Docking Station interface expansion module and possibly another peripheral. HC peripheral A peripheral located in the HC resident expansion module which is connected to the same serial channel as the Docking Station. Docking Station An ASICS located on the main Docking Station PCB which remains connected ASIC to the serial channel irrespective of the state of DLA. Notes 1. The term "local computer" implies the computer local to the LIF connector, i.e. the HC, HC-DOS or Workabout, as opposed to a "remote" computer which might be connected via a Docking Station resident expansion module, for example. 2. The term "remote" implies something on the other side of the LIF connector to the computer. 3. The term "local" implies something on the computer side of the LIF connector including devices on an HC resident expansion module. HC PROGRAMMING GUIDE Psion HC build variant and accessories matrix KEY: @ Compatible X Not compatible / not available HC | HC | HC HCR HC Workabout y : 100 | 110 | 120 | 400/800 | Docking Docking Build variants 900 Station | Station alter peeled a se (ee [ca at ee iii Galea a a DE SG Hl Sa SR ps eee alee SE eee ee HC Expansion modules RS232 / Parallel (printer) version 1 not CE 1502-0001, 25 way D type (F) + 9 way Mini DIN FCC Class B, CE-mark, E-mark, EN60950 RS232 / Parallel (printer) version 2 1502-0052, 15 way High Density + 9 way D type (M) FCC Class B, CE-mark, E-mark, EN60950 RS232 / TTL-RS232 1502-0039 (IP64), 1502-0040 (NON IP64) 9 way D type (F) + 9 way D type (M) FCC Class B, CE-mark, E-mark, EN60950 e e e e e e UK Modem (ASIC 8) 1502-0010 RJ 11 connector BABT Approved in UK, BS6301 (Safety) APPENDIX A TECHNICAL SPECIFICATIONS HC | HC | HC Workabout : . 100 | 110 | 120 | 400/800 | Docking Docking Build variants Station | Station Barcode only HP Wand HBCS-A207 + Plug + EXMOD 1502-0020 Wand Welch Allen + Plug + EXMOD 1502- 0021 FCC Class A / VDE Class B RS232 / Barcode 1502-0044 bG=Je] eGo 9 way D type Quick Loc(F) + 9 way D type (M) FCC Class B, CE-mark, E-mark, EN60950 MCR / Scanner / RS232 1502-0003 MiniDIN connectors: Scanner NipDenso + Plug (1502-0022) Scanner DigVision + Plug (1502-0023) Magnetic Card Reader + Plug (1502-0024) FCC Class B / VDE Class B LIF-PFS / RS232 (available on request) 9 way D type (M) + 9 way LIF- PFS (M) FCC Class B, CE-mark, E-mark, EN60950 LIF-PFS / TTL-RS232 (due 1995) 9 way D type (F) + 9 way LIF- PFS (M) FCC Class B, CE-mark, E-mark, EN60950 LIF-PFS / Barcode 1502-0043 9 way D type Quick Loc(F) + 9 way LIF- PFS (M) FCC Class B, CE-mark, E-mark, EN60950 TTL-RS232 / LIF-RS232 (Vehicle) 9 way D type (F) + 9 way LIF- RS232 (M) 16550 RS232 / TTL-RS232 (1502-0045) 9 way D type (F) + 9 way D type (M) FCC Class A Fast Docking Station (Fast Charger with Holster) Peet Sapte Charger Fast Charger without Holster (not yet available) al i a Trickle Docking Station (Trickle Charger with Holster) e HC PROGRAMMING GUIDE HC Workabout Docking Docking Station Station HC | HC | HC ; 2 100 | 110 | 120 | 400/800 Build variants Charger Trickle Charger without Holster (not yet xX available) Additional | Nicad battery pack 600 mA (1503-0005) Reise lea ae ae accessories 15 way high density to 25 way Centronics convertor cable (2403-0026) APPENDIX B SAFETY AND EMISSIONS APPROVALS Safety and emissions technical terms explained CE EN60950 EN55022 FCC TEC IP GS From 1 January 1996 all electrical and electronic equipment, that fall within the scope of 89/336/EEC (‘The EMC Directive’), sold in the EU must have a CE Mark. The European Norm (i.e. a specification recognised throughout the EU) for Safety of Information Technology Equipment. The European Norm for Emissions from Information Technology Equipment. It is known as a 'Product Specific Standard’. Stands for Federal Communications Commission which is the body in the USA for providing equipment authorisation. Class B are the emission limits the FCC have set for residential equipment. Class A are the emission limits for commercial equipment. Psion equipment for sale in the USA needs to meet the appropriate requirement. Stands for the International Electrotechnical Commission which is a standards body recognised by most western countries. IEC801 is known as a 'basic standard’ and is divided into various parts, one of which covers static. The 801 series cover susceptibility, or immunity. Stands for International Protection. It gives a measure of how weatherproof a product is. Stands for Gepriifte Sicherheit ("Proof of safety"), which is used in Germany to indicate safety. INDEX .btf files HC, 3-1 -mas files HC ROM build, 5-1 16550 RS232 /TTL RS232 module specification HC, A-12 application keyboard restriction on HC, 2-9 programs example HC, 2-4 asynchronous processing HC, 2-3 asynchronous I/O HC, 1-7 asynchronous programs HC, 3-2 ATTRIBUTE HC command, 3-7 AUTO HC command, 3-7 BACKLIGHT HC command, 3-8 bar code interface specification HC, A-17 bar code reader module - version 2 specification HC, A-15 batch file processing HC, 3-1 BATCHK HC command, 3-8 BATTERY HC command, 3-8 CD HC command, 3-9 CE mark approvals Europe, B-1 Class B (FCC) USA, B-1 command from remote PC HC, 3-3, 3-4 command implementation HC, 3-7 command line editor HC, 3-3 command shell copies of HC, 3-3 HC, 3-1 start up HC, 3-18 terminating auto HC, 3-4 terminating non auto HC, 3-4 command syntax HC, 3-7 communication with other computers HC, 1-13 CONFIG HC command, 3-9 converter cable - 15 Way to 25 specification HC, A-7 COPY HC command, 3-9 copy protection ROM customisation HC, 1-13 cradle HC, 1-3 specification HC, A-20 Cradle connections hardware HC, 4-1 connections software HC, 4-2 HC introduction, 4-1 port C HC, 4-1 CRD: device driver HC, 4-5 customising hardware HC, 1-10 HC, 1-10 software HC, 1-10 D HC command, 3-10 database support HC, 1-7 DATE HC command, 3-10 DELETE HC command, 3-10 DEVICE HC command, 3-10 device drivers for HC, 2-9 devices CRD: driver HC, 4-5 PMX: driver HC, 4-4 DIR HC command, 3-11 directories and files HC, 3-4 display HC, 1-4 docking cradle HC, 1-3 docking station specification HC, A-21 DOS not on HC, 1-14 emast.exe HC ROM building utility, 5-1 utility program, 5-1 HC PROGRAMMING GUIDE EN55022 standard Europe, B-1 EN60950 standard Europe, B-1 ENV HC command, 3-11 environment variables HC ROM, 5-6 EPOC explained HC, 1-6 erom.exe HC ROM building utility, 5-1 HC ROM utility, 5-2 utility program, 5-1, 5-2 European safety and emissions approval - technical terms, B-1 safety and emissions approvals, B-1 European Norm, B-1 EXIT HC command, 3-11 expansion modules HC, 1-3 FCC Class A standard USA, B-1 FCC Class B standard USA, B-1 Federal Communications Commission USA, B-1 file access remote HC, 1-8 file name specifications HC, 3-6 file names command parameters HC, 3-5 file paths command parameters HC, 3-6 files in HC ROM, 5-3 ROM based HC, 1-9 files and directories HC, 3-4 files in use error HC, 3-4 FORMAT HC command, 3-11 FREE HC command, 3-12 gauge example program HC, 2-5 graphics calls example HC, 2-6 graphics calls gauge example HC, 2-6 GS (Gepriifte Sicherheit) German safety, B-1 hardware basic HC, 1-2 customising HC, 1-10 HC .btf files, 3-1 ii application keyboard restrictions, 2-9 asynchronous I/O, 1-7 asynchronous processing, 2-3 asynchronous programs, 3-2 batch file processing, 3-1 CLIB programming, 2-1 command implementation, 3-7 command line editor, 3-3 command shell, 3-1 command shell copies of, 3-3 command shell start up, 3-18 command shell terminating auto, 3-4 command shell terminating non auto, 3-4 command syntax, 3-7 communication with other computers, 1-13 concept behind, 1-1 copy protection ROM customisation, 1-13 cradle, 1-3 Cradle connections hardware, 4-1 Cradle connections software, 4-2 CRD: device driver, 4-5 customising, 1-10 database support, 1-7 device drivers, 2-9 directories and files, 3-4 display, 1-4 EPOC explained, 1-6 example gauge program, 2-5 example hello world program, 2-4 example lined program, 2-6 example programs, 2-4 expansion modules, 1-3 fast serial port, 1-3 file access remote, 1-8 file name command parameters, 3-5 file name specifications, 3-6 file path command parameters, 3-6 files and directories, 3-4 files in use error, 3-4 graphics calls gauge example, 2-6 graphics window server, 1-6 hardware basics, 1-2 hardware customising, 1-10 hssram.sys configuring, 4-3 introduction to, 1-1 keyboard, 1-5 Link connection high speed, 4-2 lithium batteries caution, 1-4 mastcpy, 1-12 master SSD, 1-12 memory internal, 1-2 multi-tasking, 1-6 not DOS, 1-14 path default, 3-5 pausing screen display, 3-3 PLIB explained, 1-6 PLIB programming, 2-1 PMX/HSS mechanism, 4-3 PMX: device details, 4-4 PMX: driver, 4-4 power supply, 1-4 processor, 1-2 program launching, 3-1 programming choices, 2-1 programming for, 2-1 programming languages, 2-1 remote commands from PC, 3-3, 3-4 reprogramming, 1-11 reproing, 1-11 resetting, 1-11 ROM customisation, 1-12 romwrite, 1-12 screen, 1-4 shell process writing, 2-9 shell replacing, 1-10 software basic, 1-5 software customising, 1-10 software versions, 1-6 specification, A-3 SSDs, 1-2 switching on for first time, 1-1 synchronous processing, 2-3 synchronous programs, 3-2 terminating programs, 3-2 user interface programming, 2-2 window server buffer flushing, 2-6 HC command ATTRIBUTE, 3-7 AUTO, 3-7 BACKLIGHT, 3-8 BATCHK, 3-8 BATTERY, 3-8 CD, 3-9 CONHIG, 3-9 COPY, 3-9 D, 3-10 DATE, 3-10 DELETE, 3-10 DEVICE, 3-10 DIR, 3-11 ENV, 3-11 EXIT, 3-11 FORMAT, 3-11 FREE, 3-12 KILL, 3-12 LDEV, 3-12 LINK, 3-13 LOWBAT, 3-13 LPROC, 3-14 LSEG, 3-14 MASTER, 3-15 MD, 3-15 NOTIFY, 3-15 OFFENABLE, 3-15 RD, 3-15 RENAME, 3-16 RESUME, 3-16 SET, 3-16 SETDATE, 3-16 SUSPEND, 3-17 INDEX TERMINATE, 3-17 TYPE, 3-17 VER, 3-17 WAIT, 3-17 WNOTIPFY, 3-18 HC Cradle introduction, 4-1 specification, A-20 HC docking station specification, A-21 HC modem (UK) specification, A-18 HC ROM mas file, 5-1 .mas file creating, 5-6 -mas file required files, 5-7 building utility emast.exe, 5-1 building utility erom.exe, 5-1 customisation options, 5-4 customising, 5-1 environment variables, 5-6 files in, 5-3 master file, 5-1 master file creating, 5-6 master file creation, 5-2 master file requirde files, 5-7 master SSD, 5-1 mastering cautionary notes, 5-1 size consideration, 5-4 utility erom.exe, 5-2 version numbers, 5-3 hello world example program HC, 2-4 hssram.sys configuring HC, 4-3 IEC801 standard International, B-1 International Electrotechnical Commission standards, B-1 IP (International Protection weather proofing), B-1 keyboard HC, 1-5 restrictions on HC, 2-9 KILL HC command, 3-12 launching programs HC, 3-1 LDEV HC command, 3-12 library services ROM based HC, 1-9 LIF - RS232 cable specification HC, A-26 LIF connector specification HC, A-27 lined example program HC, 2-6 Link connection high speed HC, 4-2 ill HC PROGRAMMING GUIDE LINK HC command, 3-13 lithium batteries caution HC, 1-4 LOWBAT HC command, 3-13 LPROC HC command, 3-14 LSEG HC command, 3-14 mastcpy HC, 1-12 MASTER HC command, 3-15 master file creating HC ROM, 5-2, 5-6 required files HC ROM, 5-7 master SSD HC, 1-12 ROM HC, 5-1 MCR /RS232 /TTL RS232 module - version 2 specification HC, A-9 MCR interface specification HC, A-9 MD HC command, 3-15 memory internal HC, 1-2 modem - HC (UK) specification, A-18 multi-tasking HC, 1-6 NOTIFY HC command, 3-15 OFFENABLE HC command, 3-15 parallel interface - 15 way high density specification HC, A-7 parallel Interface specification HC, A-5 path default HC, 3-5 pausing screen display HC, 3-3 PLIB explained HC, 1-6 PMX/HSS mechanism HC, 4-3 PMX: device details HC, 4-4 driver HC, 4-4 port C Cradle HC, 4-1 power supply HC, 1-4 processor HC, 1-2 programming choices for the HC, 2-1 CLIB for the HC, 2-1 iv for the HC, 2-1 languages for the HC, 2-1 PLIB for the HC, 2-1 programs example gauge HC, 2-5 example HC, 2-4 example hello world HC, 2-4 example lined HC, 2-6 pseudo static RAM PSRAM, A-2 PSRAM versus SRAM, A-2 RD HC command, 3-15 remote file access HC, 1-8 RENAME HC command, 3-16 reprogramming HC, 1-11 reproing HC, 1-11 resetting HC, 1-11 RESUME HC command, 3-16 ROM customisation HC, 1-12 customisation options HC, 5-4 customising HC, 5-1 other components HC, 1-9 ROM based library services HC, 1-9 romwrite HC, 1-12 RS232 / bar code reader module specification HC, A-16 RS232 / RS232 TTL interface technical specification, A-9 RS232 /TTL RS232 interface (9-way D-type) specification HC, A-10 RS232 /TTL RS232 module (16550) specification HC, A-12 RS232 interface specification HC, A-11, A-13, A-16 RS232 interface specification HC, A-5, A-6 RS232 TTL interface specification HC, A-12, A-14 RS232/Parallel (printer) module specification version 2 HC, A-5 RS232/Parallel (printer) module version 1 specification HC, A-4 safety and emissions approvals Europe, B-1 technical terms, B-1 screen HC, 1-4 SDD pseudo static RAM PSRAM, A-2 PSRAM, A-2 serial port fast HC, 1-3 SET HC command, 3-16 SETDATE HC command, 3-16 shell replacing HC, 1-10 shell process writing for HC, 2-9 software basic HC, 1-5 customising HC, 1-10 versions HC, 1-6 solid state disks specifications, A-1 specification technical 16550 RS232 /TTL RS232 module, A-12 bar code interface HC, A-17 bar code reader module - version 2 HC, A-15 converter cable - 15 Way to 25 Way HC, A-7 docking station HC, A-21 HC, A-3 HC Cradle, A-20 LIF - RS232 cable HC, A-26 LIF connector HC, A-27 MCR /RS232 /TTL RS232 module - version 2 HC, A-9 MCR interface HC, A-9 modem - HC (UK), A-18 parallel interface - 15 way high density HC, A-7 parallel Interface HC, A-5 RS232 / bar code reader module HC, A-16 RS232 / RS232 TTL interface, A-9 RS232 /TTL RS232 interface - version 2 HC, A-10 RS232 interface, A-11 RS232 interface HC, A-5, A-6, A-13, A-16 RS232 TTL interface, A-12 RS232 TTL interface HC, A-14 RS232/Parallel (printer) module - version 1 HC, A-4 INDEX RS232/Parallel (printer) module - version 2 HC, A-5 solid state disks, A-1 SSDs, A-1 vehicle interface box HC, A-19 SRAM versus PSRAM, A-2 SSD specifications, A-1 SSDs HC, 1-2 SUSPEND HC command, 3-17 switching on first time HC, 1-1 synchronous processing HC, 2-3 synchronous programs HC, 3-2 TERMINATE HC command, 3-17 terminating programs HC, 3-2 TYPE HC command, 3-17 user interface programming the HC, 2-2 utility program emast.exe, 5-1 erom.exe, 5-1 vehicle interface box specification HC, A-19 VER HC command, 3-17 version numbers HC ROM, 5-3 WAIT HC command, 3-17 window server buffer flushing HC, 2-6 graphics HC, 1-6 WNOTIFY HC command, 3-18