PSION SERIES 3/3A SOFTWARE DEVELOPMENT ====================================== Series 3 (and Series 3a) applications may be developed either in OPL or in C. The facilities available in both languages are such that, whichever language is used, there need not be any 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. 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. 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 or Series 3a and its Programming Manual, * an IBM PC or compatible, * a text or program editor, such as Brief, to run on the PC, * a PC version of the Psion 3Link cable and the associated software, * optionally, a Series 3 or Series 3a emulator to run on the PC, * optionally, the HC OPL/g SDK and/or the Documentation version of the SIBO C SDK. Full documentation of the OPL language itself is contained in the Programming Manuals, supplied with all Series 3 and Series 3a machines. *** HC OPL/g SDK The HC OPL/g Software Development Kit provides a PC environment for developing OPL programs. Although primarily aimed at developers writing for the Psion HC range of machines, the majority of the information it contains is applicable to developing OPL programs for any Psion computer. The version of OPL supplied on Series 3 and Series 3a computers is a superset of the OPL/g version that is described in this SDK. In addition to a comprehensive set of PC-based development software tools, the SDK contains a programming guide and an extensive library of OPL procedures. These procedures perform many commonly required operations, including the provision of direct access to services provided by the EPOC operating system. The SDK also contains an explanation of the SIBO hardware and an OPL-oriented description of I/O devices. *** SIBO 'C' SDK The SIBO C Software Development Kit 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. As well as 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 Reference manuals, * access the EPOC O/S 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 and the OPL program translator, hhtran.exe. This is supplied, together with full explanatory documentation, with the HC OPL/g SDK. It is also provided, together with an explanatory text file, as part of the 3Link software). Using this development environment, the program can be written and translated on the PC. If a Series 3 emulator is available, initial testing may also be carried out on the PC. For final testing the program must be transferred, via 3Link, to a Series 3. C Development ------------- An application written in C must be developed on a PC. For such development you will need: * a Series 3 or Series 3a, * an IBM PC or compatible, * a text or program editor, such as Brief, to run on the PC, * a PC version of the Psion 3Link cable, * at least those elements of Clarion TopSpeed C and the Psion C development environment that are provided by the Standard version of the SIBO C SDK, * optionally, a Series 3 or Series 3a emulator to run on the PC. *** CLIB or PLIB? An application developed in C may make use of either of two C libraries: CLIB or PLIB. CLIB contains standard functions, familiar to most C developers, and described in TopSpeed's C Library Reference manual. A developer who wishes to port an existing application to a SIBO machine with a minimum amount of effort would use CLIB. A pure CLIB program is, however, restricted to a much simpler user interface than is possible when using PLIB. The PLIB library is more closely matched to the EPOC architecture and will, in general, result in a smaller program than the equivalent CLIB version. In addition, it provides access to many of the EPOC system services that are not available in CLIB. There is, however, more to learn for a programmer already familiar with standard C libraries. A compromise route is possible, since a CLIB program may also use PLIB functions. *** Object Oriented Programming Developers writing for the Series 3 and Series 3a machines may choose to write their applications with the aid of Psion's Object Oriented programming system. This is the system used by Psion in the development of application software. Applications written using this system can make use of the extensive Object Oriented libraries that are built into the ROM of all Series 3 machines. As a result, such applications can be more sophisticated and flexible than those written in "straight" C. *** The C development process 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. This can conveniently be done with the aid of the SIBO debugger that is provided with the 'C' SDK. Those parts of the software that do not depend on user interface code specific to the Series 3 may be debugged locally, on the PC. If a Series 3 or Series 3a emulator is available, initial testing may also be carried out on the PC, but final testing must take place on the target machine. The Psion SIBO 'C' Software Development Kit ------------------------------------------- The Psion SIBO 'C' Software Development Kit provides the information necessary to develop C language applications for the Psion SIBO family of hand-held and notebook computers, including the Series 3 and Series 3a. The 'C' SDK is available in three variants: Documentation (Doc) Standard (Std) and Professional (Prof). *** SIBO C SDK Doc (part no 1505-0014-03) The Documentation variant contains: * three volumes of SDK documentation, containing fourteen manuals, * the Psion software environment, including libraries, header files and associated software tools, * example program source code that relates to the documentation. This variant is not sufficient by itself to develop SIBO applications in C. It would be suitable for the following reasons: * you already have the Clarion TopSpeed C package, * you require additional copies of the documentation, say, for design purposes, * you wish to upgrade to a later version of the SDK, * you wish to evaluate the SDK development environment, * you intend to develop applications in OPL. *** SIBO C SDK Std (part no 1505-0013-03) In addition to the material supplied in the Documentation variant, the Standard variant contains: * TopSpeed C, the Clarion C compiler and library, * TopSpeed Environment, the Clarion multi-window editor and project system. This variant 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 variant would be suitable if: * you intend to develop C applications for any of the SIBO range of computers, * you do not already have the TopSpeed C package. *** SIBO C SDK Prof (part no 1505-0012-03) In addition to the material supplied in the Documentation and Standard variants, the Professional variant contains: * the Clarion TopSpeed TechKit, including the TopSpeed assembler, * the Clarion TopSpeed C Library Source Kit, containing the source code (both C and assembler) for the C library that is supplied with the compiler, * Psion SIBO CLIB C library source. This variant would be suitable for the following reasons: * you develop substantial applications for the PC as well as for SIBO machines, * you wish, or need, to write at least part of your code in assembly language, * you need to have control over the C library. 'C' SDK documentation --------------------- The 'C' SDK documentation consists of fourteen manuals, in three volumes, covering a wide range of features of SIBO architecture and the SIBO 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 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 and is robust against run-time errors, such as shortage of memory. *** The SIBO Debugger The SIBO C source-level debugger, supplied with all variants 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 SIBO 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 computers. The topics discussed include: Writing software for the HC, The HC command Shell, Customising the HC ROM. *** Series 3/3a Programming Guide This manual contains information that is specific to the development of applications for the Series 3 and 3a computers. The topics discussed include: Series 3 Programming Overview - including 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 an application of Shutdown and Switchfiles messages, and the modification of an application's behaviour by means of the technique of aliasing, Enhanced Sound Output. *** Programming in HWIF HWIF (the Handheld Wimp InterFace) is a library of user interface routines suitable for use by C developers producing applications for the Series 3 computers. 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, 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 and Text fonts. Again, 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 (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 The Object Oriented Programming Guide describes the tools and techniques needed to design and develop Object Oriented application software for Series 3 and Series 3a machines with the aid of Psion's Object Oriented programming system. It is a practical guide to the writing of Object Oriented applications and contains many code examples. This manual explains the use of the basic window, menu, dialog and event-management classes, and the handling of and recovery from errors. More advanced topics include the editing of formatted text and access to the printer services. *** OLIB Reference The OLIB Reference manual contains a full description of all the object classes included in the OLIB object library. This library provides the basic control mechanisms that are common to all Object Oriented applications, together with a wide range of data and file management classes. Topics include: Variable Array Classes ('container' classes) Timers Editable Documents File Management Resource Files Inter-process Communication