Technical Reference Manual

SYSTEM VERSIONS

SYSTEM VERSIONS

The table below lists all organiser models. Note that the Organiser Mark 1 is included for completeness, but is not covered by this manual.

Most of the base models were also produced as POS (Point Of Sale) versions, either with a full alphanumeric keyboard (POS-250,350,4xx), or a numeric one (POS-100,200,296).

The difference between the normal operating system and the POS variants is in the handling of the top level. The normal operating system enters the top level menu and then dispatches to the various services available, while the POS machines do the following:

1. Boot all devices.
2. Scan all devices for an OPL procedure called BOOT
3. If the procedure is not found then display INSERT PACK and switch off after 1 second.
4. If the procedure is found then run the procedure.
5. Repeat the above steps.

Also, the numeric-only keyboard models switch to numeric mode automatically.

IDENTIFICATION BYTES

In order to allow the machine type to be determined as well as the software revision level of the ROM, there are 4 identification bytes. They occupy the following addresses:

• $FFE7 - Language(s)-byte
• $FFE8 - Model-byte
• $FFE9 - Version number
• $FFCB - Model-byte-2 (introduced with model LZ)

Language-byte

This was introduced in version 3.6 of the Organiser OS. Earlier versions are english only and this byte usually is $FF.

Bit 7 of this byte set, indicates that the machine is multi-lingual. The value of the remaining seven bits then gives either the language or selection of languages implemented. Further values may have been added as new language variants were introduced.

See also: Foreign Languages

Model-Byte

The base model type and the special model type are held together in the model byte. The base model type is held in the bottom 3 bits of this byte and the special model type is a single bit set in the remaining 5 bits. The base model type is for identifying the ROM/RAM configuration AND the Operating System.

NOTE: The ROM/RAM configuration alone does not determine the base model type.

Note that these features are totally independent.

Model-byte-2

Version Number

OPERATING SYSTEM VARIANTS

CM/OS

• $FFE8 = $00

The CM/OS is the base operating system from which all other operating system variants are derived. As such any software written to run on the CM/OS is guaranteed to run on all other operating system variants. In other words software is upwardly compatible between the operating systems.

XP/OS

• $FFE8 = $01 - XP machine.
• $FFE8 = $11 - XP POS 250 machine.
• $FFE8 = $41 - XP Alpha POS 200 machine.
• $FFE8 = $81 - XP POS 200 machine.
  

As for the CM/OS but will support the following extra facilities:

• 128K Datapacks
• Rampacks
• Bar Code Readers
• Swipe Readers

LA/OS

• $FFE8 = $02 - LA machine.
• $FFE8 = $12 - LA POS 250 machine.
• $FFE8 = $42 - LA Alpha POS 200 machine.
• $FFE8 = $82 - LA POS 200 machine.
  

As for the XP/OS with the exception that the memory allocator is completely different.

This is because the system variables are located at $2000 in the CM/OS and XP/OS as external RAM only starts at this address. However in the LA machines external RAM starts at address $400. In order to keep the operating systems compatible the system variables are still located at address $2000 in the LA machines.

The free RAM is therefor in two sections, between $400 and $2000 and above the system variables. In order to allow the operating system to use the extra 7K of RAM the memory allocator effectively joins these two discontinuous areas of RAM together.

Note that XP and LA were both labelled XP.

LZ/OS

• $FFE8 = $0E LZ/OS - LZ machine.
• $FFE8 = $1E LZ/OS - POS-432 machine.
• $FFE8 = $0D LP/OS - LZ64 (LP) machine.
• $FFE8 = $1D LP/OS - POS-464 machine.

The operating system in the LZ is fully back-compatible with the previous Organiser II operating systems but has many extensions. All system variables are at the same addresses as on the standard Organiser and all system services will work exactly as they did before. Some system services have been extended to use the 4-line screen and there are 51 new services together with new system variables.

FOREIGN LANGUAGES

Foreign languages were introduced in version 3.6 of the Organiser OS. Earlier CM/XP machines were English only. Besides models for a single foreign languages also a multi-lingual XP, offering eleven languages, was produced.

The LZ operating system is multi-lingual and offers English, French and German. All Organiser text, menus and error messages are automatically translated when a new language is selected. The LCD display in the LZ facilitates foreign characters and these can be typed in when the appropriate language is selected - SHIFT-RIGHT-ARROW is used to select foreign characters for the next key press only. For example, when the language is set to French, SHIFT-RIGHT arrow followed by 'a' produces the character 'á'..

The following section applies only to multilingual machines.

LANGUAGE SELECTION ON COLD START

When the machine is switched on from a 'cold start', the language menu is presented (after displaying the copyright message). One language MUST be selected (ON/CLEAR will do nothing) before the top-level menu is displayed in the language chosen.

Devices are also rebooted whenever a language is selected.

These two functions (displaying the language menu and booting the devices) can be disabled to allow bootable software to 'take over' the machine on a cold start. To do this the flags in XTB_COLD described below are used.

CHANGING LANGUAGE

To switch languages under program control, the system service TL$LSET must be used. BTB_LANG should not be poked directly.

SYSTEM VARIABLES

BTB_LANG ($2186)

VALUES: 0 for English, 1 for French, 2 for German, 3 for Spanish, 4 for Italian, 5 for Portuguese, 6 for Swedish, 7 for Danish, 8 for Norwegian, 9 for Dutch, 10 for Turkish

The default value, 0, is the value before any language has been chosen so that devices booted on cold start will boot in English.

BTB_LANG can be be read at any time but should not be written to directly (TL$LSET must be used).

XTB_COLD ($232E)

XTB_COLD stores 2 flags:

• Bit 7 is set to disable the language selection menu.
• Bit 0 is set to disable the 'second boot' after language selection.

These flags can be read or written to at any time. Note that if bit 7 is set, the second boot will still take place unless bit 0 is set. XTB_COLD is reset to zero after language selection is attempted.

SYSTEM SERVICES

TL$LSET

Sets the language. If the language requested is not available, English is selected. The top-level menu is re-initialised so any 'inserted items' will be removed.

It is possible to get an error if there is insufficient room in RAM for the new top-level menu (different languages have different sized top-level menus). If an error occurs, the language is unchanged.

CM/XP/LA RELEASE NOTES

What follows are notes for the different releases of CM and XP machines. This list was published in 1987, further versions have been released later.

Last known release: 3.7

All significant enhancements and known bugs are listed. All the bugs noted are fixed for the following release.

VERSION 2.3 AND EARLIER

Not released in any quantity.

RELEASE 2.4

Released on 12th May 1986.

ENHANCEMENTS:

• Devices booted when the Organiser is cold booted.

BUGS:

• Machine may crash a on a cold boot if the install code of a device alters the menu.
• Rebooting a machine with more than one device installed may cause a crash.
• An attempt to translate the illegal statement "11SIN" results in a crash.
• If a field is assigned to that is beyond those already assigned to before it may write the data over the diary or operating system variables. This can, in rare cases, result in a crash. The fix is to assign (a null string or zero) to the last field after creating or opening a file and after getting an END OF FILE condition. (The END OF FILE condition is when EOF is non-zero, this means that all values of the fields have been zeroed out.)
  If you know what they tried to express by that, please send me a note! <boris>
• If the diary is backed over midnight and then brought forward, using the arrow keys, any diary entries seem to have disappeared.
• If RAM is full, editing a procedure can give OUT OF MEMORY and leave the screen corrupted.
• If an error is encountered when adding to or subtracting from a calculator variable (M0 to M9) then the variable is corrupted.
• Floating point AND produces unreliable results.
• VIEW(1,"") does not work properly.
• VIEW of a 255 character string doesn't scroll.
• Strings longer than 255 can be declared (e.g. 256 gives a zero length string).
• Declaring arrays which overflow memory size can cause machine to crash at run-time. e.g. LOCAL s$(255,100) or LOCAL a(10000).
• INPUT A.A$ artificially limits the length input to 252 minus the record size (as found from RECSIZE). It should allow 254 characters.
• If the machine is turned off in the minute before an alarm is due it won't go off for 34 minutes.
• If packs are accessed at the same time as the buzzer is used (e.g. from a key click) the bottom byte of the pack can, very rarely, be blown to zero.

RELEASE 2.6

Released on 15 October 1986.

ENHANCEMENTS:

• Checksum on RAM pack header.
• Battery checking improved.
• Can call OPL programs on device D.
• INFO calculates FREE memory as percentage free of the total memory less the operating system.
• OPL string comparison become case dependent.
• UDGs preserved when the Organiser is turned off.
• Intelligent, faster NEXT - works on one pack at a time.
• A POSITION to an illegal place, e.g. past the end of file, used to leave the position alone. It now it positions to the last or first record as appropriate.

BUGS:

• If after a successful CLOSE another CLOSE is done when no files are open it can crash the system.
• It is possible but unlikely to get spurious alarms when loading devices.
• If the ON/CLEAR is pressed at the same moment as an alarm it may be missed.
• When a translator error is detected some memory may be lost until the language is run.
• Using MENU with an item with more than 17 letters causes an infinite loop.
• Deleting a null diary entry causes the next diary entry to be deleted.
• TRAP DELETE "A:"+XXX$: can cause a crash if there is an error in XXX$:.
• Using logical name D can cause OPEN to fail with error number zero. As an error of zero is not reported at the top level, it is safest not use logical name D.
• POS200 ONLY. The menu cell is grown every time the machine is booted so memory eventually fills up. Solution is to cold boot the machine.

INTRODUCED BUGS:

• Sizing 8, 16 & 32K packs can fail even when the pack is good.
• Erasing records on RAMPAKS followed by APPEND may corrupt the PACK. Can be solved by avoiding using UPDATE and doing FIRST after using ERASE.
• Copying MK1 packs fails with PACK CHANGED error.

RELEASE 3.1

Released on 30 January 1987

ENHANCEMENTS:

• If a file is OPENned/CREATEd/DELETEd without a specified device it takes the last device used (as opposed to a random device).
• Reports CHR$(256) and negative arguments to LEFT$, RIGHT$ and MID$ as errors.
• Intelligent NEXT improved works with 1 file on each device.
• LA split device loader.
• 128K RAM packs supported.
• Faster deleting on RAM packs.

LZ RELEASE NOTES

What follows are notes for the different releases of LZ machines. This list was published in 1989, further versions have been released later.

Last known version: 4.6

All significant enhancements and known bugs are listed. All the bugs noted are fixed for the following release.

RELEASE 4.2

Released on: 16th March 1989

• Memory 'grabbed' by devices (e.g. capture buffer in CommsLink) is not shown in INFO.
• If LOW BATTERY is detected during a cold start, garbage ALARMS are set.
• SORTING a file which contains other records interspersed within its own will cause 'extra' records to be added at the front of the file.
• SORT does not order records containing the same character repeated different numbers of times correctly, e.g. AA and A.
• If there is an error in when saving a DIARY (e.g. PACK FULL) during TIDY, the DIARY is still be deleted.
• If a match string > 10 characters is passed to any of the WILD CARD OPL FUNCTIONS (e.g. DIRW) the machine will crash.
• OPL VIEW of a null string will crash the machine. Also DISP(0,"string") will crash.
• If part of a password is typed on entry to a notepad and then left to time out - it beeps and clears the password, then prompts for the password again.
• If memory is full and a notepad is attempted to be entered, OUT OF MEMORY is displayed the first time but the 2nd time a new notepad is created.
• "Load..." is displayed without clearing the screen on entry to the notepad.
• In the DIARY "nn entries shortened" says 10 when there is 100 etc.
• In WORLD "The Hague" is shown as "The Hage"
• Alarms go off accurate to within 1 minute only. They should be exact.
• If part of an OPL procedure or NOTEPAD is received with COMMS-LINK and the connection is broken, the machine may crash.
• A bootable pack created on the DEVELOPER runs OK in 2-line mode but if CommsLink is present as well, it runs in 4-line mode.
• There is a chance of getting a garbage ALARM going off during RESET.
• There are some errors in the GERMAN text.
• Calling OPL EDIT with an 80 character prompt, e.g. AT 20,4 :PRINT "X": :EDIT A$ does not work correctly.

RELEASE 4.3

Released on: 24th April 1989

• If a "workday" alarm is set for the Friday before the end of a month whose last day falls on a Saturday or Sunday, some corruption may occur when the alarm goes off or if you attempt to set an alarm on the Saturday or Sunday following the Friday.
  On version V4.2 you will get a DEVICE MISSING error but on V4.3 it will appear to be OK. In both versions there may be corruption and there may be a possibility of the machine TRAP'ing.
  The dates it will occur on are as follows:
  

RELEASE 4.4

Released on: 8th May 1989