SIBO 'C' Software Development Kit SERIES 3/3A PROGRAMMING GUIDE Version 2.
(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.
Contents 1 Series 3 Programming Overview...........................................................................................1-1 Programming possibilities ...............................................................................................1-1 Differences between .app files and .img files....................................................................1-2 Add-file lists.............................................................................................................
GENERAL PROGRAMMING MANUAL 3 Enhanced Sound Output........................................................................................................3-1 Introduction.....................................................................................................................3-1 Sound on the Series 3 ......................................................................................................3-1 Introduction ...............................................................................
CHAPTER 1 SERIES 3 PROGRAMMING OVERVIEW Throughout the Series 3 Programming Guide, reference to the Series 3 machine should be taken to include the Series 3a and the Workabout unless stated otherwise. See also the Workabout Programming Guide for further information specific to that machine. Programming possibilities In general terms, there are six different levels at which programs can be written for the Series 3: • using OPL, creating .opo or .
SERIES 3/3A PROGRAMMING GUIDE Other parts of the SDK that may be found of particular relevance to programming for the Series 3 include: • the descriptions of file formats used by various applications, in the Additional System Information manual • a description of the special form of printer driver files used on the Series 3, also in the Additional System Information manual.
1 SERIES 3 PROGRAMMING OVERVIEW Running programs via RunImg An alternative to installing a program in the System Screen with its own file list is to run it from the RunImg icon: • the user presses TAB while the highlight is within the RunImg file list • the user navigates the file selector until it selects the program file • the user presses ENTER to start this program. This procedure can be simplified if the program is placed in a top-level \img\ directory, and given the extension .img.
SERIES 3/3A PROGRAMMING GUIDE An example of code that attempts to locate a resource file in the second add-file slot of a .app file is as follows: GLDEF INT rscfile_rs_init(PR_RSCFILE *self,TEXT *name) { ImgHeader head; /* self->rscfile.offset is zero by default */ f_open(&self->rscfile.pcb,name,P_FRANDOM|P_FSTREAM|P_FSHARE); if (p_read(self->rscfile.pcb,&head,sizeof(head))==sizeof(head)) { if (!p_scmp(&head.Signature[0],"ImageFileType**")) { /* we have a .img file */ if (!(self->rscfile.offset=head.
1 SERIES 3 PROGRAMMING OVERVIEW Avoid $ signs The '$' sign is used in names of environment variables created and manipulated by Psion system software. All external applications should completely avoid using environment variables with '$' signs in them unless they first secure the agreement of Psion. The plan is to extend the use of '$' to mean, not just "used by Psion", but rather "licensed by Psion". Interested software developers who contact Psion will be given a short identifier - for example, "$17$".
SERIES 3/3A PROGRAMMING GUIDE 1-6
CHAPTER 2 COMMUNICATING WITH THE SYSTEM SCREEN Introduction An important aspect of the Series 3 is the way all the built-in applications communicate with the System Screen application (also known as the Shell application): • The name of any file currently open is displayed in bold in the file list in the System Screen • This name is also displayed in any status window shown • On a request from the System Screen, an application can close itself down tidily, saving any changes to file as appropriate •
SERIES 3/3A PROGRAMMING GUIDE The second line in a .ms file gives the default directory for an application. This can be left blank for non file-based applications. For example, the .ms file for the built-in Time application could be Time 8000 with the second line left blank. The third line in a .ms file gives the type of the application (sometimes called the type number of the application). A .ms file can have fourth, fifth, sixth ...
2 COMMUNICATING WITH THE SYSTEM SCREEN • A type of 2 is used to restrict a file based application such that only one copy can run at any one time - this is the case for the built-in World application. In contrast see types 0 and 3. • A type of 3 means that the application a) will have a file list when installed in the System Screen, and b) can receive Switchfile instructions. More than one copy of the application can be run at any one time.
SERIES 3/3A PROGRAMMING GUIDE Applications which are intended to be capable of being run on either mono- or multi-lingual Series 3s should adopt the multi-lingual form of .ms file, and simply accept that the public name will be incorrect on mono-lingual machines.
2 COMMUNICATING WITH THE SYSTEM SCREEN Creating .als files An .als file is produced from a .ma file and a .pic file by running the tool makeals. The three files all have the same root name (ie disregarding the extensions). For example, the command makeals letter produces the file letter.als from letter.ma and letter.pic. The .pic file is the icon to use. The process of creating .pic files is discussed in the previous chapter. The .ma file is a source file similar in format to a .ms file.
SERIES 3/3A PROGRAMMING GUIDE The program editor mode is available on all machines. In this mode there is no access to the style and emphasis subsystems, the corresponding menu commands being replaced by options to "translate", "run", "show error" and set "indentation". In this mode, the first letter of the alias info denotes the nature of the program that is being edited. It actually identifies the program to invoke to effect any "translate" and (possibly) "run" commands from the user.
2 COMMUNICATING WITH THE SYSTEM SCREEN Epoc reserved statics The values of the Epoc reserved statics DatProcessNamePtr, DatLocked, DatStatusNamePtr, and DatUsedPathNamePtr all have special significance for Series 3 applications. The values of these variables for different applications are read at various times by the System Screen and also by the Window Server.
SERIES 3/3A PROGRAMMING GUIDE Additionally, files with the "hidden" attribute set are never displayed in a file list in the System Screen unless the file is open within an application (in which case it will be displayed in bold). In order to check for the existence of hidden files or file starting with Sys$ in a directory, the user should press TAB to enter "directory" mode of the System Screen.
2 COMMUNICATING WITH THE SYSTEM SCREEN In case DatUsedPathNamePtr is null, the value of the string at DatProcessNamePtr (if any) is used instead: failing that, the process name (as returned by p_pname) is used. Initially, the name of the open file is part of the command line (see below). However, when this has to be changed - either as a result of an Open or Save as command inside the application, or in response to a Switchfile request from the System Screen - a new buffer has to be used for this purpose.
SERIES 3/3A PROGRAMMING GUIDE The <29> immediately following the zero at the end of the first zero terminated string indicates that the remainder of the command line is 0x29 bytes long - as is indeed the case.
2 COMMUNICATING WITH THE SYSTEM SCREEN From command line to reserved statics As mentioned earlier in this chapter, an application should analyse its command line on start-up, and should write various values from this command line into Epoc reserved statics as a result.
SERIES 3/3A PROGRAMMING GUIDE Creating directories when required In contrast to file selectors on other systems, those on the Series 3 allow users to specify paths that do not yet exist. This can happen fairly commonly, for example as follows: • The user inserts a brand new solid state disk into drive A • A Save as or New file menu command is invoked • The user adjusts the disc selector to this new disk • The user types eg "Backup" into the filename editor.
2 COMMUNICATING WITH THE SYSTEM SCREEN In either case, the initial event prompts the application to call wGetCommand, to obtain the so-called new command line giving more details about the event. Contents of the new command line for System Screen messages The parameter passed to wGetCommand must be the address of a buffer having at least P_FNAMESIZE (128) bytes. The new command line is written into this buffer.
SERIES 3/3A PROGRAMMING GUIDE For example, the following code provides a successful multi-lingual alias for Word.app: #include #include #include #include #include #define R_STRARRAY_APPNAMES 78 GLREF_D UBYTE *DatCommandPtr; GLDEF_D GLDEF_D GLDEF_D GLDEF_D TEXT TEXT TEXT TEXT olibDyl[]="OLIB.DYL"; shellImg[]="ROM::SYS$SHLL.IMG"; wordNameFmt[]="ROM::%s.
2 COMMUNICATING WITH THE SYSTEM SCREEN #pragma restore GLDEF_C VOID main(VOID) { TEXT fSpec[P_FNAMESIZE]; UBYTE comBuf[E_MAX_COMMAND_BUFFER+1]; TEXT *pCommand; TEXT *pAlias; TEXT *pEndAlias; TEXT *p; HANDLE pId; INT len; p=skipStr(DatCommandPtr); len=(*p); pCommand=(p+1); pAlias=skipStr(pCommand); pEndAlias=skipStr(pAlias)-1; /* Point to end 0 */ p=p_bcpy(&comBuf[0],pCommand,pEndAlias-pCommand); p=p_bcpy(p,&aliasInfo[0],sizeof(aliasInfo)); p_bcpy(p,pEndAlias,len-(pEndAlias-pCommand)); if ((pId=p_enter2(g
SERIES 3/3A PROGRAMMING GUIDE 2-16
CHAPTER 3 ENHANCED SOUND OUTPUT Introduction The Series 3 and Series 3a provide distinct sets of sound services. The Series 3 as supplied can emit only buzzer sounds, DTMF dialling tones, and simple alarm sounds. However, by loading a suitable device driver, such as SNDFRC.LDD, the machine can also be made to emit sequences of musical notes of variable duration, thus greatly extending its sound capabilities. The first section of this chapter describes use of the SNDFRC.
SERIES 3/3A PROGRAMMING GUIDE The way to check the device driver is loaded is to make the call p_loadldd("SNDFRC.LDD"); where the full path of the .ldd file can be given. (The .ldd file has to be copied onto the Series 3.) The return values zero and E_FILE_EXIST can both happily be ignored. Other errors are more serious they probably mean that the file sndfrc.ldd cannot be located. In this case, the program cannot continue (at least, not as according to its original intention).
3 ENHANCED SOUND OUTPUT Example #include #include #include GLDEF_C INT main(VOID) { INT ret; VOID *mcb; UWORD buf[10]; UWORD len; WORD musstat; ret=p_loadldd("SNDFRC.
SERIES 3/3A PROGRAMMING GUIDE When to install and de-install the ldd file Once sndfrc.ldd has been installed, it occupies about 1.7 K of RAM. For this reason, it would seem to be best to de-install it, when the application terminates. The way to do this is to call (see the Plib Reference manual for more details) p_devdel("MUS:",E_LDD); This call will fail if another application currently has an open channel to MUS:. Applications should ignore any errors from p_devdel.
3 ENHANCED SOUND OUTPUT • sound can be played on only one channel by passing the other channel a length of zero for the note buffer - i.e. zero notes. • the P_FSET service sets both the volume and the beats per minute. The P_FSENSE service can be requested first to ensure that one or other parameter remains unchanged. To create a sound.img file simply type make sound in the appropriate directory.
SERIES 3/3A PROGRAMMING GUIDE p_ioc5(pcb,E_FSSOUNDCHANNEL1,&sndstat1,&buf1[0],&l1); p_ioc5(pcb,E_FSSOUNDCHANNEL2,&sndstat2,&buf2[0],&l2); waitstat2(&sndstat1,&sndstat2); p_close(pcb); if (sndstat1 != 0 || sndstat1 != 0) p_exit(0)); } GLDEF_C INT main(VOID) { WORD notes1[] = {1048,24,524,12}; WORD notes2[] = {1048,4,1320,4,1568,4,2092,4,1568,4,1320,4,1048,12}; WORD len1 = sizeof(notes1)/4,len2 = sizeof(notes2)/4; INT i; for (i = 0; i < 6; i++) { play_notes(¬es1[0],¬es2[0],len1,len2,i,-1) p_sleep(1); }
CHAPTER 4 USE OF SPY.APP Introduction This chapter describes the Spy application for the Series 3. This application contains many features that may help to "debug" problems with applications on the Series 3. The version of Spy described in this chapter is suitable for use on both the Series 3 and the Workabout, and can also be used on the Series 3a. A built version of spy.
SERIES 3/3A PROGRAMMING GUIDE The data displayed is updated every time Spy comes into foreground, and also whenever the Update menu option is selected. By default, it is also updated regularly on a timer, though this can be disabled by a menu option. The Refresh rate option governs how frequently updates take place, when the timer is enabled. There are in all twelve pieces of data that can be displayed for each process, but only three of these can be seen at any one time.
4 USE OF SPY.APP Other data The "Process ID" of a process is essentially the address of the control block of the application in the Operating System data space, although the top nibble reflects how many times that same slot has been reused since the last reset (the top nibble will therefore always be zero for sys$mang, sys$fsrv, and sys$wsrv). When processes talk to each other, for example in conjunction with the Bring menu option, they need to know each other's PID ("Process ID").
SERIES 3/3A PROGRAMMING GUIDE 4-4
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 Series 3a Technical Specification Physical characteristics Part numbers: Size Weight Screen Keyboard Sound and recording 1600-0029-10 (256KB) 1600-0025-10 (512KB) 1600-0080-10 (1MB) 1600-0082-10 (2MB) 165mm x 85mm x 22mm (6.5"x 3.0"x 0.9"). 275g (including batteries).
SERIES 3/3A PROGRAMMING GUIDE Expansion Peripherals Socket: External peripherals (such as a modems and printers) can be connected via a fast serial interface (1.536 Mbits/sec), which accepts optional 3Link parallel and serial interfaces. The Serial 3Link allows communication with other computers. PC Card adapter. SMS cables for Nokia and Orange mobile phones. 3Fax fax modem, (superseded by PC Card adapter). 6-way two row rectangular (male, with retracting protective cover).
APPENDIX A: TECHNICAL SPECIFICATIONS Expansion Peripherals Socket: External peripherals (such as a modems and printers) can be connected via the fast serial interface (1.536 Mbits/sec), which accepts optional 3Link parallel and serial interfaces. The Serial 3Link allows communication with other computers. 6-way two row rectangular (male, with retracting protective cover).
SERIES 3/3A PROGRAMMING GUIDE Expansion Peripherals Socket: External peripherals (such as a modems and printers) can be connected via the RS232 port which accepts optional PC Link and Parallel Printer Link cables. The PC Link allows communication with other computers. Travel Modem. PC Card adapter. SMS cables for Ericsson, Nokia and Orange mobile phones.
APPENDIX A: TECHNICAL SPECIFICATIONS Communications Infrared: IrDA SIR optical link, for IR communications and printing. The Siena does not have the DYL file in ROM to support the AccessIr API (for Infrared beaming), this is provided with this SDK and must be loaded before third party programs using this API can be used. The Siena does not have the DYL file in ROM to support the IrLPT API (for Infrared printing), this must be loaded before third party programs using this API can be used.
SERIES 3/3A PROGRAMMING GUIDE Safety: EN60950 Physical Pod with lead for connection to the Series 3 or LIF adaptor. Pod incorporates "auto wake up" switch. Replaceable lead to connect the pod to the other computer or peripheral. Complete connection is functionally equivalent to a 'null modem' cable. RS232. Masked ROM in the 3Link pod. This contains the script language and supporting communications software. The pod appears as SSD drive C.
APPENDIX A: TECHNICAL SPECIFICATIONS 9 6 8 7 5 4 2 1 3 See the Psion Series 3 3Link (RS232) manual provided with the 3Link for full details of operation.
SERIES 3/3A PROGRAMMING GUIDE Serial Printer cable (Series 3c/Siena) - Technical Specification Part number: Compatibility: EMC: 1602-0017-01 Psion Series 3c and Psion Siena only. FCC Part 15 Class B; CE Mark Safety: EN60950 Connectors: Low Profile Honda type custom connector RS-232 25 way D-type connector (male) Psion PC Link cable Technical Specification The Psion Series 3c and Psion Siena machines use this new type of communications cable.
APPENDIX A: TECHNICAL SPECIFICATIONS Psion 9-to-25 way D-type adapters - Technical Specification The Psion series 3c and Psion Siena machines use a different type of communications cable from preceding machines;- the Psion PC Link cable. To connect to other 25 way D-type connector devices, adapters are needed as, unlike the 3Link cable, this is a single cable and can’t be split to change the RS232 half to connect to a serial printer or modem.
SERIES 3/3A PROGRAMMING GUIDE Printer 9-to-25 way D-type adapter - wiring diagram 9 way D - male RX - pin 3 TX - pin 2 DTR - pin 6 GND - pin 5 DSR - pin 4 RTS - pin 8 CTS - pin 7 DCD - pin 9 SHELL 25 way D - male pin - 2 pin - 3 pin - 6 pin - 7 pin - 20 pin - 5, 8 pin - 4 pin - 7 pin - 1 SHELL Psion Parallel 3Link Technical Specification Part number: Compatibility: EMC: Interface: Connectors: 1601-0003-10 Psion Series 3, Psion Series 3 and Psion Workabout with LIF adaptor only (The Psion Series 3c and
APPENDIX A: TECHNICAL SPECIFICATIONS Psion PC Card Modem Adapter - Technical Specification Variants There are three variants: • Series 3a • Series 3c • PC The PC Card Modem Adapter with a suitable PC Card modem, combined with the PsiFax software, supersedes the 3Fax modem and software for the Series 3a. For the Series 3c there is also the alternative Travel Modem.
SERIES 3/3A PROGRAMMING GUIDE Supported PC Cards: DTE formats Psion Dacom Gold Card US Robotics WorldPort Pace Microlin Megahertz X JACK Series Nokia Cellular Data Card Philips Mobile Data Card Hayes PC Cards Dr. Neuhaus Fury Cards and many other popular models PC Modem Cards can be inserted at any time and recognised by the card adapter (hot swapping) 8N1,7E1,7O1 Flow control RTS/CTS Data transfer rates: 300 Baud to 57.
APPENDIX A: TECHNICAL SPECIFICATIONS Psion Travel Modem Technical Specification Physical Part number: Series 3/3s compatibility: Series 3a compatibility: Workabout compatibility: Series 3c compatibility: Siena compatibility: EMC: Environment: Dimensions: Power: unknown at time of publication (available January 1997) No No No Yes No FCC Part 15 Class B; CE Mark Operating temperature: 0-50C Operating humidity: 0-95% non-condensing 165mm x 40mm x 25mm 2 x AA batteries or optional rechargeable NiCad battery
SERIES 3/3A PROGRAMMING GUIDE Operational modes: V.21 300bps full duplex V.22 1200bps full duplex V.22bis 2400bps full duplex V.23 1200/75 full duplex 75/1200 full duplex V.27ter 4800bps fax send and receive V.29 9600bps fax send and receive Line connection: 2 wire PSTN via BT 600 type modular jack on flying lead Signal level: -9 dBm Equalisation: Transmit fixed compromise Receive automatic adaptive Interface: 600 ohm Error correction: V.
APPENDIX A: TECHNICAL SPECIFICATIONS Communications Functions: Dialling: Echo suppressor: REN: Fax operation: Computer connection Connector: Network connection Data transfer rate: Operational modes: Line connection: Signal level: Equalisation: Interface: Error correction: Data compression: Autodial/autoanswer Dial method: Call progress: Call control: Automatic answer: Mode selection: Call disconnection: BABT Approval Approval number: Autodialling (tone and pulse) modem conforming to: V.21,V.22, V.
SERIES 3/3A PROGRAMMING GUIDE Ericsson SMS SDK and SMS Cables There will be 2 types of SMS products: • SMS SDK - enables Psion Registered Developers to create applications for both vertical and horizontal markets that make use of the SMS capability provided by Ericsson’s GSM/DCS/PCS digital mobile phones; • SMS applications and SMS cables - Shrink wrapped and custom SMS applications available from both Psion and its Registered Developers.
APPENDIX A: TECHNICAL SPECIFICATIONS Cellnet SMSlink Cellnet SMSlink is a joint development between Cellnet and Psion. It is an SMS product for the popular Series 3a and Nokia 2110 combination. The Product includes: • Cable to connect Series 3a to Nokia 2110/2110i, and Philips PR747 GSM mobile phones • Series 3a software for composing, sending and receiving text messages • PC software (on floppy disc) to send text messages direct from PC to GSM mobile phones.
SERIES 3/3A PROGRAMMING GUIDE Vodaphone Telenote Link Vodaphone Telenote Link is a joint development between Vodaphone, Nokia and Psion. It is an SMS product for the popular Series 3a and Nokia 2110 combination. Versions There are two versions of the Telenote link: • Version 1, (available from the beginning of December 95), is for use with the Nokia 2110 and Philips PR747 digital handsets; • Version 2, (available from February 96), is for use on the Orbitel 905 digital handset.
APPENDIX A: TECHNICAL SPECIFICATIONS Version Top level part number SSD: 1601-0057-01 Floppy disc: 1601-0056-01 Availability Current product. Orange Messaging Link Orange Messaging Link is a joint development between Orange and Psion. It is a messaging product which is based on the GSM SMS service but for the Orange network.
SERIES 3/3A PROGRAMMING GUIDE A - 20
APPENDIX B DIFFERENCES BETWEEN PSION SERIES 3 MODELS At the time of writing there are four current and six superseded machines in the Series 3 family. The main differences between the computers are tabulated overleaf.
SERIES 3/3A PROGRAMMING GUIDE Current models in the Series 3 family Feature \ Model Series 3c Series 3c Siena Siena Internal RAM size 2MB 1MB 1MB 512KB Internal masked ROM size 2MB 2MB 1MB 1MB Screen (pixels) 480x160 480x160 240x160 240x160 Screen (characters) 80x17 80x17 40x17 40x17 Grey scale supported 3 3 3 3 SSD drives 2 2 optional extra optional extra Communications connector R232 low profile, with power output R232 low profile, with power output R232 low profile,
APPENDIX B: DIFFERENCES BETWEEN PSION SERIES 3 MODELS Superseded models in the Series 3 family Feature \ Model Series 3a Series 3a Series 3a Series 3a Series 3s Series 3 Series 3 Internal RAM size 2MB 1MB 512KB 256KB 256KB 256KB 128KB@ Internal masked ROM size (* 2MB if Spell app included) 2MB/1MB* 2MB/1MB* 1MB 1MB 512KB 384KB or 512KB 384KB or 512KB Screen (pixels) 480x160 480x160 480x160 480x160 240x80 240x80 240x80 Screen (characters) 80x17 80x17 80x17 80x17 40x9
SERIES 3/3A PROGRAMMING GUIDE B-4
INDEX .afl files add file lists pre-defined slots S3, 1-2 add file lists S3, 1-2 .als files creating .als files S3, 2-5 creating with makeals.exe S3, 2-5 .app files versus .img files, 1-2 .img files versus .app files, 1-2 .ma files alias file source file S3, 2-5 .ms files multi-lingual S3, 2-3 shell data file source file S3, 2-1 .pcx files converting to icon files, 1-3 .pic files application icons S3, 1-2 .rsc files resource files application S3, 1-2 .rzc files resource files compressed S3, 1-2 .
SERIES 3/3A PROGRAMMING GUIDE shell data files creating from .
INDEX 3Link, A-7 Mac Link, A-8 PC Link, A-8 modem -Travel specification, A-13 multi-lingual aliasing Word app S3, 2-13 multi-lingual apps keyboards S3, 1-4 menu acceleratiors S3, 1-4 other data Spy application, 4-3 parallel 3Link specification, A-10 parallel printer link cable specification, A-10 PC (XT) 9-to-25 way D-type adapters wiring diagram, A-9 PC card modem adapter specification, A-11 PC Link cable specification Series 3c/Siena, A-8 PC serial 3Link Apple Macintosh converter, A-7 assembly components
SERIES 3/3A PROGRAMMING GUIDE PC card modem adapter, A-11, A-13 PC Link cable Series 3c/Siena, A-8 printer - parallel link cable, A-10 serial printer cable Series 3a, A-7 serial printer cable Series 3c/Siena, A-8 Series 3 - 3Link cable, A-5 Series 3/3s, A-2 Series 3a, A-1 Series 3c, A-3 Siena, A-4 Siena SSD drive, A-5 Travel modem, A-13 specifications technical modem 3Fax Series 3, A-14 Spy application, 4-1 application building, 4-1 application heap integrity, 4-2 application heap statistics, 4-2 applicati
