NOTICE I am no longer maintaining the Psionics Files. Any errors or unfinished material will remain so indefinitely.
The "Psionics Files" is my name for my project for collating information about programming the Psion Series 3 and 3a which is not in the manuals provided with the machines.
The intended audience of the files was the Series 3/3a OPL programmer. Thus, for example, material that can only be used by assembler programmers is usually (though not always) omitted, and constants are expressed as numbers rather than symbolic names. Except where explictly stated, material applies to both systems and MS-DOS emulations of both; differences are always indicated. In addition, most material also applies to the HC and MC, but differences are not always indicated. The term "Series 3t" is used to refer to the original Series 3 and the Series 3s (which is basically the original with the spreadsheet application built-in), while the term "Series 3" applies to both these and the 3a. [Note: I previously used "3s" for this. I have not altered the "last changed" date on files changed only for this purpose.]
Where Series 3c or Siena material has become available to me, I've edited the files accordingly. But in general it can be assumed that Series 3a covers the 3c and Siena.
The first version of the files was built up from information freely available, such as the standard manuals, the source code of various games, and Usenet postings. After I first posted them, the response of Psion was surprising: David Wood arranged for me to receive a complete set of SDK manuals!
According to David: the purpose of the copyright messages in the SDK is to allow Psion to express its proprietal ownership over the material. It may be copied and distributed so long as the original derivation from the SDK is acknowledged. What might cause Psion to seek legal redress is someone claiming complete credit for something that is actually derived from the SDK, and did not point readers to the SDK as the source of more information. Psion has no interest in trying to make any profit directly from sales of the SDK. Psion simply wishes the information to reach as many people as possible, trusting that, as a result, many good third party products will be written.
In addition, and subject to the above, I retain copyright in my intellectual property in these files; that is to say, the effort in editing and arranging them, and any text I have written. These files may be distributed through normal Usenet mechanisms, may be archived at sites offering free access to contents, and may be converted to other formats (such as HTML). However, all public copying and distribution is to be of the entire set of files, and not any subset, and any versions that are not a direct copy (this includes format conversions unless done completely automatically) are to carry a prominent note indicating that they have been edited and by whom, and that errors may have resulted.
While these files have been generated in good faith, there may be errors in them, and/or they may not reflect current releases of the EPOC operating system. No warranty, express or implied, is offered by myself or Psion in these matters.
This the preceeding three paragraphs are not to be removed or materially altered by any changes.
[Phew ! If you want to do something that the above doesn't cover, please contact me at clive@davros.org. I'm quite reasonable.]
The following files exist at present:
| AGENDA.FMT | Format of Series 3t Agenda (.AGN) files |
| AGENDA3A.FMT | Format of Series 3a Agenda (.AGN) files [incomplete] |
| BITMAP.FMT | Format of Bitmap (.PIC) files |
| COUNTRY.FMT | Format of Country information files |
| DBF.FMT | Format and use of Data (.DBF) files [incomplete] |
| DEVICES | Device driver interfaces |
| ENVVARS | Environment variables |
| ERRCODES | Standard Psion error codes [incomplete] |
| FILEIO | Filing system IO interfaces |
| FLASH | Format of Flash SSD cards and ROMs |
| FONT.FMT | Format of Font (.FON) files |
| IMG.FMT | Format of executable Image (.IMG/.APP) files |
| INTRO | This file |
| LINK | Description of the 3-Link protocol [not yet available] |
| KERNEL | Kernel memory organisation |
| KEYWORDS | More information about OPL keywords [incomplete] |
| LOCALES | Locale codes |
| MENUPROB | Series 3t menu problem workaround |
| MISC | Various miscellaneous notes |
| OPLSOCK | OPL interface to PsiMail TCP/IP [withdrawn] |
| OPO.FMT | Format of OPL object (.OPO/.OPA) files |
| PROCESS | Processes and their properties |
| RESOURCE.FMT | Format of resource files |
| SOUND.FMT | Format of sound (.WVE) files |
| SPR.FMT | Format of SH3 Spreadsheet (.SPR) files |
| SYSCALLS.n | System calls |
| SYSCALLS.IDX | Alphabetic index to system calls |
| TCPIP | PsiMail TCP/IP programming interface |
| WORD.FMT | Format of Word (.WRD) files |
| WSERVER | Window Server calls [several missing things] |
[Note that DATA.FMT has been replaced by DBF.FMT.]
The following terms have specific meanings:
| byte | one byte integer |
| word | two byte integer |
| trip | three byte integer |
| long | four byte integer |
| real | 8 byte floating point number |
| cstr | a string, as found in C programs, ending with the first zero byte; the contents are all non-zero bytes, the string may have zero length (excluding the terminating byte), and there is no limit on the length unless stated otherwise. |
| qstr | a string, as found in translated OPL programs, consisting of a count byte followed by that many bytes; the contents may include zero bytes, and the length is in the range 0 to 255 (excluding the count byte). |
| text | a string, whose length is expressed externally (for example, by occupying a fixed size buffer); it may contain zero bytes, and does not have an initial count byte. [This definition does not apply when the "text" is explicitly described as a cstr or qstr.] |
| address | a word (two bytes), containing the address of a variable in the same or a different address space (all address spaces are limited to 64k). It may be obtained with the ADDR keyword. |
| day number | a number of days since 1900-01-01. |
| abstime | a number of seconds since 0000 GMT on 1970-01-01 (the format used by the DATETOSECS keyword). |
| interval | a number of seconds since 0000 on the relevant day. |
All integers are little-endian. Whether a value is signed or unsigned can normally be deduced from context.
A real number uses IEEE 64 bit format, using a little-endian layout
| Bits | 0 to 51: | mantissa, with binary point at left and implicit leading 1 |
| Bits | 52 to 62: | biased exponent (1023 = value in range 1 <= V < 2) |
| Bit | 63: | sign (0 = positive, 1 = negative) |
Data structures are always shown with each field described as a byte offset from the start of the structure. Each field is given as either a start and end offset (the field including both), or as a start offset and type. Bytes not included in any listed field have an unknown meaning. Unused bytes are shown, and should be set to zero.
Hexadecimal numbers are indicated by a $ or & prefix. These are used interchangably; they do not imply the type or number of bits of the value.
Bits within bytes are always numbered from 0 (least significant) to 7 (most). Unused bits are not described, and should be set to zero.
Many operations use cstr values. These can be converted to and from qstr (OPL string) values as follows:
An at sign (@) is used to indicate incomplete or missing information, or text that I planned to rewrite.
Back to the Psion index.
Back to Clive's home page.