1. Home /
2. Psion II /
3. Psion File Formats

Psion File Formats

This text will explain the various file formats the Psion Organiser II uses.

1. Packs 1.1 Pack Header 1.2 Pack header flag byte 1.3 Trap Rampak 1.4 Bootable packs 1.5 Device Identification Number 1.6 Flash datapaks 1.7 Relocatable code block 1.8 Device Code 1.9 Device Vectors 2. General File Formats 2.1 Short Records 2.2 Long Records 2.3 Record types 2.4 Data File 2.5 Block File 2.6 Headerless blocks 2.7 Deleted records and files 2.8 Pack error correction 3. Block File Formats 3.1 CM/XP Diary files 3.2 Procedure files 3.3 Comms link setup files 3.4 Pocket Spreadsheet files 3.5 Pager setup files 3.6 LZ notepad file 4. PC files 4.1 ODB files 4.2 OPL files 4.3 OBx files 4.4 LNO file for the Organiser Developer kit 4.5 OPK file for the Organiser Developer kit 4.6 IPK file for the Organiser Developer kit 4.7 BIN file for the Organiser Developer kit 4.8 BIN file for Comms boot 4.9 ORGBAK.BUF backup file

1. Packs

First, lets examine packs, and how info is stored on them. It is important to realise that a clean datapack has all its bits set, and the organiser can only clear bits to write its data. This has many consequences for the way that data is organised.

1.1 Pack header

Every pack starts with a 10 byte header, containing the info about the pack itself. This header is written by the organiser when it 'Sizes' a pack.

Normal packs have the following header:

Once a pack has been detected or booted by the Organiser, the pack header is copied into memory. The header for slot B: is located at address $20E1 (8417) and the slot C: header is directly after that at $20EB (8427). You can use this for example to find out the size of a pack by evaluating 8*PEEKB(8418) or 8*PEEKB(8428) in the calculator for the pack in slot B: or C: respectively.

1.2 Pack header flag byte

The bits of the flag byte all have a different meaning:

Note that it is possible to clear the RDWRT and/or COPYPK bits to set the pack protection, but it is not possible to remove it again (except by copying to a new pack).

Here are some common values of the first two bytes of the header:

1.3 Trap Rampak

This is a 32k Rampak which has bit 6 of the flag byte cleared, and hence a flag byte of $3C. When a system crash occurs on a Psion organiser, a Trap interrupt is generated which jumps to a routine in the ROM. This routine prints 'TRAP' on the screen, possibly some extra information, and switches off. In ROM versions 3.6 or above, it checks whether a trap Rampak is in any of the slots and if found it will copy the Ram contents to the corresponding addresses on the pack. Of course the areas $00-$3F and $100-$400 are not copied because they are processor ports and semi-custom chip controls. Therefore those pack addresses are left untouched (so the pack header stays intact too). Note that the LZ64's extra Ram banks are not copied.

1.4 Bootable packs

A bootable pack is a pack that contains a machine code program that is loaded and run when 'the devices are booted', i.e. when ON is pressed in the main menu. The Comms link for example acts like a bootable pack, and its program inserts/deletes a menu item, and handles the new OPL commands for the link.

Bootable packs have the following header:

1.5 Device Identification Number

Officially, Identification numbers in the range $80-$C0 are reserved for Psion's hardware devices, and $00-40 for their software devices. However, the convention of using that same number for the boot priority sometimes causes conflict with those ranges. Here is a table of the Identification/Priority numbers that I have found so far.

1.6 Flash datapaks

A flash datapak (or flashpak) is a datapak that uses an EEPROM instead of an EPROM. This allows it to be electronically formatted. As the Organiser's operating system has no way of formatting or writing to these chips, the flashpak normally contains a driver to allow it to do so. The pack is therefore bootable.

It always has its write-protect bit cleared so that no attempt will be made to write to it as if it were a normal datapak. The flashpak driver instead uses the most significant bit of the 'checksum' word to signify the write protection (normally set, but cleared for write-protection).

Flashpaks have the following bootable header:

1.7 Relocatable code block

Here is a short description of the Psion relocatable object format, as used for device code on bootable packs:

• A word containing length of code block,
• the code block itself (of the length above),
• a word containing the byte checksum of the code block (i.e. sum of all the bytes in the code block)
• a word containing the number of fix-ups,
• a list of fix-ups,
• a word containing the word checksum of the fix-up list (i.e. sum of all the words in the list)

The code block is such that all absolute jumps and other absolute references are coded as if the block was at address 0. The fix-up list contains the addresses of those absolute references (with 0 meaning the first byte of the code block). When the code is loaded in memory (by using the DV$LOAD service in the ROM; SWI $1A), the new address of the code block is added at all the places indicated by the fixup list, so that all the absolute references are correct.

1.8 Device code

Device code is a program that is run when a pack (or top slot device) is booted. They are booted either when ON/Clear is pressed in the main menu, or when the system service DV$BOOT (SWI $17) is called. See bootable packs. Device code is in a relocatable code format, and its code block has the following format:

Device code is generally stored on a pack in a headerless block.

1.9 Device vectors

Device code consists of several smaller programs called vectors. By using the system service DV$VECT (SWI $1B) any vector on any booted device can be called (register A should contain the device number, B the vector number).

Generally, a device must have at least 3 special vectors, which are detailed below.

Pressing ON/Clear in the main menu (or using service DV$BOOT, SWI $17) will first call the remove vector of all devices (using service DV$CLER, SWI $18) and remove all device code from memory. Then all device code is loaded, calling the install vector in the process.

If a procedure call is encountered in a program or in the calculator, (the service DV$LKUP, SWI $19, is called so that) the procedure name is passed to the language vector of all devices in turn. If the carry flag is set, then none of the devices accept it and the packs are searched for a normal OPL procedure of that name. If a device returns with a clear carry flag, then the appropriate vector is immediately called (registers A and B are already prepared for calling service DV$VECT, SWI $1B).

2. General File Formats

There now follows a description of the various file types that can be stored on a pack. Two types of record are used for storing files.

2.1 Short Records

A short record is used for storing file names, and for records in data files. It has the following format:

2.2 Long records

A long record is used for a large block of data, for example the data of a procedure, and has the following format:

2.3 Record types

The record type bytes that the organiser uses are as follows:

Note that when a record or file is deleted, the high bit of the record type byte is cleared, so record types 01-7E signify deleted files/records.

2.4 Data file

A data file, for example the MAIN file, consists of a header, and its separate data records. The header is a short record of record type $81 and length 9, in which the data consists of the file name (padded to 8 characters with spaces) followed by its file identifier byte (range $90-FE). In other words:

Every data file on a pack must have a unique File Identifier byte. The data records of a data file are short records, which use the file identifier byte as their record type, i.e.

The header and data records of a file can be interspersed by any number of other records and files. When a data file is deleted, all the records and its header are individually marked as deleted, so that the file identifier byte can be reused when a new file is created on a pack.

Also the header need not come before the first record of a file, because when a file is renamed, the header is deleted and rewritten (with the new name but the same file identifier) at the end of the pack. The header of the MAIN file is written on the pack during 'Sizing', so it has file identifier byte $90. The MAIN file should not be renamed or deleted.

2.5 Block files

Apart from data files explained above, the only other files the organiser uses are block files. These are files in which the data is stored as one block in a long record. A block file consists of a file name header, followed immediately by a long record:

followed by:

2.6 Headerless blocks

Sometimes a long record is used without preceding it with a header. The most common use for this is for storing device code. Generally it is the first new item on the pack, following directly after the pack header and the MAIN file header. This places the device code at pack address $0019 ($0A bytes in the pack header, $0B bytes in the MAIN header, 4 bytes in the long record header).

2.7 Deleted records and files

Note that when a record or file is deleted, the high bit of the type byte is cleared, so file types 01-7E signify deleted files/records.

When a block file is deleted, the file header is marked deleted, but the long record is not changed (see error correction for the meaning of a 00 type byte). When a data file is deleted, all its data records are marked as deleted as well as its file header, allowing the file identifier to be reused.

The data file header usually precedes the data records of that file, but this is not true if the file has been renamed. When a data file is renamed, the old header is deleted, and a new one is written at the end of the pack, using the same file identifier byte.

2.8 Pack error correction

The Psion uses a simple but fairly effective system to recover from errors when writing to a pack. When a pack is sized, the organiser checks that all bytes are set to FF (or else a pack not blank error occurs). If the pack header cannot be written, the pack is unusable.

If an error occurs when writing the first byte of a short or long record, then the second byte is left untouched, and the organiser tries again at the next address. Therefore a 'record type' of FF means that the two bytes should be ignored.

This method fails if the incorrect length byte has become 0 or $FF. The byte 0 is taken by the organiser to mean that the pack has been removed. The byte $FF on the other hand signifies (especially when followed by another $FF) that the end of the data is reached, and that new data can be written there.

If an error occurs when writing the length word of a long record, then the type byte is marked deleted, so that it becomes in effect a deleted short record with length 2. The file header is then also deleted, and the organiser tries again at the next address.

3. Block File Formats

There now follows a description of the content format of various types of block files. Unfortunately not all are complete, due to being difficult to reverse-engineer.

3.1 CM/XP Diary files

These are block files of type $82. Its data block consists of a list of entries which is terminated by a zero-byte. Each entry has the form:

3.2 Procedure files

These are block files of type $83. The data block consists of two parts, both preceded by a length word. The first part contains the object code of the procedure (i.e. the translated code), the second the source code (i.e. the typed OPL).

The object code data is too complicated to explain here, for full details see Translated Procedures and QCodes. A procedure which has not been translated will have an object code block of length zero.

The source code data consists of text, with each line terminating in a zero-byte. The first line must contain a title ending in a colon. In an object-only procedure, the source code block is of length zero.

Procedures translated by the emulator in the Organiser Developer are block files of type FE. For details of these files, again see Translated Procedures and QCodes.

3.3 Comms link setup files

These are block files of type $84, containing the saved settings for the Comms Link. Its data block consists of 27 bytes exactly, containing the parameters:

3.4 Pocket Spreadsheet files

These are block files of type $85. This is a complicated file type, and I have not yet been able to work out the exact specifications.

3.5 Pager setup files

These are block files of type $86 containing the saved settings for the Pager. Its data block consists of 119 bytes exactly. There are many bytes that seem to have fixed values and which are not actually used by the Wordcall Pager I have, but it may be that other types of Pager make use of those bytes to store further settings.

It is clear that in the first part of the file, each numerical setting is preceded by a byte that indicates the range of values the setting has, for instance all settings that only allow On/Off (00/01) are preceded by 01. The bytes at 07-08 and 18-21 therefore probably represent settings that other Pagers could use, such as Pagers that can also send messages. The byte at 07 containing the '>' character could be some kind of prompt.

3.6 LZ notepad file

These are block files of type $87. Its data block consists of two parts, the header, and the data, both preceded by a length word. The header has the form:

The data consists of text with zero-bytes indicating the end of a line (so the data ends in zero). The first line must contain a title ending in a colon. If a password has been set, all the data after the title is encrypted. Note that the title, the colon after the title, and if present the zero-byte immediately following the colon, are all left unencrypted.

For an in-depth description of the password system and the notepad encryption, see The Psion LZ Password System page.

4. PC files

When a file is transferred via a Comms link to another computer, its format is changed somewhat. Here the various PC files are described.

4.1 ODB files

These are data files which have been sent to a PC. The file name extension is ODB. This is an ordinary ASCII text file. Each record is placed on a single line, and tab characters (ASCII code 9) are used to separate the fields. No line may be longer than 254 characters.

4.2 OPL files

These are procedures which have been sent to a PC. The file name extension is OPL. This is an ordinary ASCII text file, containing only the source of the procedure. No line may be longer than 254 characters.

4.3 OBx files

These are block files which have been sent to a PC. The file name extension is OBx where x is the low nibble of the file type, i.e. OB3 for a translated procedure, OB7 for a notepad file etc. The file has the following format:

4.4 LNO files for the Organiser Developer kit

These are files containing a translated procedure, similar to an OB3 file. It has file type FE instead of 83. For the details of these files, see Translated Procedures and QCodes.

4.5 OPK file for the Organiser Developer kit

These are pack image files. It contains all the data of a pack, and has the following format:

There is a slight ambiguity with this format. When BLDPACK is used, the length integer includes the final FFFF bytes, so that it is 6 less than the OPK file size. When UNMAKE is used, the length integer does not include the FFFF bytes, so that it is 8 less than the OPK file size. In practice this does not matter, since writing FF bytes to an empty part of a pack changes nothing.

4.6 IPK file for the Organiser Developer emulator

These pack image files are used in the emulator that is part of the Organiser Developer kit, and the format is almost identical to the OPK file format:

The length integer includes the final FFFF bytes at the end of the pack data, but not any of the padding that may follow.

4.7 BIN file for the Organiser Developer kit

These files are used by the BLDPACK program in the Organiser Developer kit for constructing bootable packs. It has the following format:

The format of bytes 6+ are basically used as the first part of the pack. As such, it could probably be chosen to be different from the standard format outlined above, as long as it generates a valid pack image.

4.8 BIN file for Comms boot

These files are loaded by the Comms link BOOT option. They simply contain the standard device code (i.e. a relocatable code block) without any preceding or subsequent bytes. There are a few differences from standard device code. The device code block is like this:

4.9 ORGBAK.BUF backup file

This file contains a backup of the RAM of the organiser, including the contents of device A:, diaries, alarms, etc. It is created by running the TRANS.BIN Comms boot code, and loaded back into the organiser by running the RECV.BIN boot code.

This file consists of separate blocks. Each block starts with a length word, which is the length of the block including the length word itself. The third byte is the type of block. This type byte can have the following values: