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.......................................................................................................... 1-1 The HC concept .............................................................................................................. 1-1 Switching on and off ................................................................................................ 1-1 Switching on for the first time.................................................................................. 1-1 The basic hardware ......................................................................................................... 1-2 Processor.................................................................................................................. 1-2 Internal memory....................................................................................................... 1-2 Solid state disks (SSDs)............................................................................................ 1-2 Types of SSD ........................................................................................................... 1-2 Expansion modules .................................................................................................. 1-3 The Fast Serial port and the Cradle .......................................................................... 1-3 Power supply............................................................................................................ 1-4 Caution regarding lithium batteries .......................................................................... 1-4 Screen ...................................................................................................................... 1-4 Keyboard.................................................................................................................. 1-5 The basic software........................................................................................................... 1-5 Versions of the HC software..................................................................................... 1-6 The terms Epoc and Plib explained........................................................................... 1-6 Graphics window server ........................................................................................... 1-6 Multi-tasking kernel................................................................................................. 1-6 Support for asynchronous i/o.................................................................................... 1-7 Database support functions....................................................................................... 1-7 Support for remote file access................................................................................... 1-8 Other ROM-based library services............................................................................ 1-8 Other ROM components........................................................................................... 1-9 Customising an HC......................................................................................................... 1-9 Hardware customisation ........................................................................................... 1-9 Replacing the built-in Shell......................................................................................1-10 Resetting the HC ...................................................................................................... 1-10 Reproing the HC ...................................................................................................... 1-11 Master SSDs and mastcpy ........................................................................................ 1-12 Once-off ROM customisation using Romwrite.......................................................... 1-12 Customisation for copy-protection ............................................................................ 1-12 Connecting to other computers........................................................................................ 1-13 Basics of serial connections to an HC ....................................................................... 1-13 RS232 connections................................................................................................... 1-13 Summary of straightforward usage of Link on the HC .............................................. 1-13 Why not MS-DOS? ......................................................................................................... 1-14 2 Writing Software for the HC ................................................................................................ 2-1 Basic programming choices............................................................................................. 2-1 Choice of programming language............................................................................. 2-1 Standard C (Clib) or Psion C (Plib) .......................................................................... 2-1 Writing the user interface......................................................................................... 2-2 Synchronous or asynchronous processing ................................................................. 2-3 Example programs.......................................................................................................... 2-4 A graphics version of Hello World ........................................................................... 2-4 The Gauge application ............................................................................................. 2-5 The need to flush the Window Server buffer ............................................................. 2-6 Other graphics calls in Gauge................................................................................... 2-6 A suite of line editor functions.................................................................................. 2-6 Full specification of the lined functions .................................................................... 2-8 General comments .......................................................................................................... 2-9 Device drivers for the HC......................................................................................... 2-9 Writing a customised shell process........................................................................... 2-9 Developing applications on restricted-keyboard HCs ................................................ 2-9 GENERAL PROGRAMMING MANUAL 3 HC Command Shell............................................................................................................... 3-1 Overview......................................................................................................................... 3-1 Batch file processing ................................................................................................ 3-1 Launching programs ................................................................................................ 3-1 Synchronous programs and asynchronous programs................................................. 3-2 Terminating programs.............................................................................................. 3-2 The command line editor.......................................................................................... 3-3 Pausing the screen display........................................................................................ 3-3 Additional copies of the Command Shell.................................................................. 3-3 Sending commands from a remote PC ...................................................................... 3-3 More on running programs remotely ........................................................................ 3-4 Auto-terminating and non-auto-terminating Command Shells.................................. 3-4 Files and directories ........................................................................................................ 3-4 File In Use error messages........................................................................................ 3-4 Default path and current directory............................................................................ 3-5 Specifying