1. Overview of the Series 3 Development Environments Series 3 applications may be developed either in OPL or in 'C'. The facilities available in both languages are such that, whichever language is used, there is often no great difference in terms of the appearance of the application to the user. Generally speaking, an application written in 'C' will be more responsive and may use less memory than one written in OPL. Large applications, or those that are critically dependent on speed will benefit from being written in 'C', which provides the potential to create a more sophisticated application than is practical in OPL. In particular OPL has no special debugging facilities. For many applications, however, the difference may not be significant. Development in OPL involves a much smaller learning curve, particularly if the programmer is not already familiar with the 'C' language. 1.1 OPL Development Although it is possible to develop OPL programs on the Series 3 itself, this is impractical for most non-trivial applications. To develop an application in OPL you will therefore need: - a Series 3 and its programming manual, - an IBM PC or compatible, - a text or program editor, such as Brief, to run on the PC, - a IBM PC version of the Psion Serial 3Link product. - optionally but highly recommended, the Psion 'C' Software Development Kit (SDK) Documentation. Full documentation of OPL is contained in the Series 3 Programming Manual, supplied with all Series 3 machines. The 'C' SDK contains much material of a general nature that will be of use to an OPL programmer. There is a close parallel between the actions of OPL keywords and facilities provided for programming in 'C'. In addition to providing more detailed information about such actions, it will be of particular interest to those who wish to: - Make use of the asynchronous I/O services by means of the IOA, IOWAIT, IOWAITSTAT, IOSIGNAL, KEYA, and KEYC keywords. Using these can greatly improve the responsiveness of a program - the techniques involved are extensively described, notably in the PLIB Reference and the I/O Devices References manuals, - access the EPOC Operating System services via the OPL CALL and OS mechanisms that can greatly extend the capabilities of an OPL program. These services are fully described in the EPOC O/S System Services manual. In addition to these manuals, the basic Series 3 OPL development environment on the PC consists of a program editor, the OPL program translator HHTRAN.EXE (provided, together with an explanatory text file, as part of the 3Link software) and the resource compiler RCOMP.EXE. Using this development environment, the program can be written and translated on the PC. The program is then transferred, via 3Link, to a Series 3 for testing. 1.2 'C' Development An application written in 'C' must be developed on a PC. For such development you will need: - a Series 3, - An IBM PC or compatible, - a text or program editor, such as Brief, to run the PC, - the IBM PC version of the Psion Serial 3Link product, - the Psion SDK Standard version which includes the TopSpeed C compiler (see section 1.2.1), Developing in 'C' Programs are written on the PC using either the TopSpeed Environment or another program editor, such as Brief. When successfully compiled and linked the program is transferred to and run on the Series 3, normally with the aid of the SIBO debugger that is provided with SDK. Those parts of the software that do not depend on the user interface code specific to the Series 3 may be debugged locally on the PC. Why TopSpeed 'C'? TopSpeed 'C' was developed by Jensen & Partners Int. (JPI) and is now owned by Clarion Inc. Psion use this less usual 'C' because in does pure small model (the ES register is never corrupted) and because, thanks to its flexible calling conventions, it produces code 10-15% smaller than most 'C' compilers. SIBO is the name given to Psion's hardware architecture common to the Series 3 and HC ranges. EPOC is the name of the operating system. 1.2.1 The Psion Software Development Kit The Psion 'C' SDK provides the information necessary to develop 'C' language applications for Psion SIBO based Products. The SDK is available in three flavours: Documentation, Standard and Professional. Psion 'C' SDK Documentation (part number 1505-0014 01) The Documentation contains: - three volumes, divided into fourteen manuals, - the Psion software environment, including libraries, header files and associated software tools, - includes the Object Oriented Programming (OOP) documentation, - a range of example program source code that relates to the documentation. The version is not sufficient to develop SIBO applications in 'C'. It is designed for developers who: - already have the TopSpeed 'C' Environment, - require additional copies of the documentation, say, for design purposes, - wish to evaluate the Psion SDK development environment, - intend to develop applications in OPL. Psion 'C' SDK Standard (part number 1505-0013 01) In addition to the material supplied in the Documentation version, the Standard version contains: - TopSpeed 'C' compiler and library, - TopSpeed Environment, a multi-window editor and project system. This version contains all the system software necessary to develop SIBO applications in 'C'. The TopSpeed 'C' components may be used independently of the Psion SDK components both to learn 'C' programming and to write 'C' programs to run on a PC. This version is suitable for developers who: - intend to develop 'C' applications for any of the SIBO ranges of Psion computers, - do not already have the TopSpeed 'C' environment. Psion 'C' SDK Professional (part number 1505-0012 01) In addition to the material in the Standard version, the Professional version contains: - the TopSpeed TechKit, including the TopSpeed assembler, - the TopSpeed 'C' Library Source Kit, containing the source code (both 'C' and assembler) for the 'C' library that is supplied with the compiler, - Psion CLIB 'C' library source. This version is suitable for developers who: - wish, or need, to write at least part of the code in assembly language, - need to have control over the 'C' library. Levels of programming: Programming level Requirement Optional OPL Series 3/3a PC, Comms Link OPL + system calls + SDK documentation PC, Comms Link 'C' + SDK Standard, PC, Serial Link Advanced 'C' + SDK Professional The 'C' libraries documented in SDK: CLIB 'C' Library Easiest for porting existing 'C' programs (and programmers). Restricted i/o. PLIB Psion Library Extra library functions to utilise more of the features of the Series 3. Restricted i/o. Generates much smaller code than CLIB because it is really just a layer over ROM code. HWIF Handheld Wimp Gives access to dialogs, menus and edit InterFace boxes. A 'C' layer over the object- library oriented HWIM. WLIB Psion Windows Gives more flexibility when drawing to Library the screen. The object-oriented libraries: HWIM Handheld Called by HWIF. Documented in SDK V2.0. Windows Icons and Menus OLIB Psion Object Gives access to the built in objects. Library This gives an application full access to all facilities in the ROM. eg multi- threaded programming. Documented in SDK V2.0. FORM Formatted For more complex edit boxes. Not yet text documented. These libraries can be mixed. A professional application will generally not use CLIB. They are ranked in order of accessibility. 1.2.2 SDK 'C' documentation The 'C' SDK documentation consists of fourteen manuals, in three volumes, covering a wide range of features of the SIBO architecture and development system. General Programming Manual This manual explains how to install the SDK and how, by means of simple examples, to build an application that will run on a Psion SIBO machine. It describes in detail the differences between the CLIB and PLIB 'C' libraries and also gives guidance on copy protection. The important Fundamental Programming Guidelines chapter explains the basic principles that should be understood by all developers of SIBO applications. It includes advice on how to ensure that an application: - remains responsive to user input, - is robust against run-time errors, such as shortage of memory. The SIBO Debugger The SIBO 'C' source-level debugger, supplied with all versions of the SDK, runs on a PC. It is normally used for remote debugging of an application running on a SIBO machine but may, in some circumstances, also be used to debug SIBO applications running on the PC. The debugger is specifically designed to facilitate the debugging of applications running in the EPOC environment, in which the application's code segment may be relocated at any time. This manual describes the facilities provided by the debugger and explains its use. HC Programming Guide This manual contains information that is specific to the development of applications for the rugged and highly configurable HC range of hand-held computers. The topics discussed include: - writing software for the HC, - the HC command Shell, - customising the HC ROM. Series 3 Programming Guide This manual contains information that is specific to the Series 3 pocket computer. The topics discussed include: - Series 3 Programming Overview - advice on writing multi- lingual applications, - communicating with the System Screen - including the differences between file-based and non-file based applications, - the receipt by applications of Shutdown and Switchfiles messages, and the modification of an application's behaviour by means of the technique of aliasing, - enhanced Sound Output. Programming HWIF HWIF (the Hand-held Wimp InterFace) is a library of user interface routines suitable for use by 'C' developers producing applications for the Series 3 computer. The HWIF library provides easy and efficient access to many aspects of Series 3 functionality, including sophisticated printing and the presentation of menu bars, dialog boxes and edit boxes. The manual contains a range of worked examples as well as a comprehensive description of all HWIF routines. Additional System Information The Additional System Information manual explains a variety of topics, including the MCLINK communications software (this forms part of the Psion serial 3Link product), resource files, printer drivers, the file formats used by applications and the writing of device drivers. PLIB Reference This manual contains a comprehensive description of the PLIB 'C' function library. The library routines are classified into fourteen areas of functionality and each group is accompanied by background information, usage recommendations and example code. Window Server Reference This manual contains a description of the WLIB library. This library provides an interface to the window server built into each SIBO machine, supplying a range of sophisticated graphics operations. The topics discussed include: - windows, - graphics output, - keyboard input, - bitmaps, - text fonts. The descriptions are accompanied by example code. I/O Devices Reference This manual describes the I/O device drivers that have been written by Psion. The description of each driver includes a full explanation of the services that it supports, together with example code. ISAM Reference The ISAM Reference (Indexed Sequential Access Method) dynamic library provides a powerful set of functions to access record- and field- structured files of the type that are manipulated by OPL programs and the database applications on SIBO machines. The ISAM Reference manual explains, with the aid of example code, how to load and use the ISAM library, and contains a complete description of the ISAM functions. EPOC O/S System Services This manual contains a complete description of the software interrupt interface to ROM-based system services, classified into 21 areas of functionality. An appendix lists the services both alphabetically, by service name, and numerically, by interrupt and function number. This will be of particular interest to OPL and assembly language programmers. Hardware Reference The Hardware Reference manual contains a description of the SIBO computer hardware, including the principal chip set, expansion ports and the SIBO serial protocol. Object Oriented Programming Guide (applies to Series 3 Range only) This contains a description of classes, categories, objects, methods and property. It explains how the built in objects may be used with a practical guide to using WIN, DLGBOX, LODGER and other classes under HWIM. OLIB reference This has details of a numerous classes including: TIME, variable array classes (similar to container classes in C++), RSCFILE (Resource Files), CLEANUP, APPMAN (Application Manager), ACTIVE, and TIMER. It also describes the IPCS (Inter Process Communications Service) and Link Paste.