Jaap's Psion II Page

Home / Psion / LZ Technical Manual
ORGANISER II MODEL LZ /LZ64 TECHNICAL MANUAL, VERSION 1.0   (LZTECH.DOC)


(c) Copyright Psion Ltd 1989. All rights reserved. This Technical
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 permission of Psion PLC, is prohibited. Reverse engineering
is also prohibited.

The information in this document is subject to change without notice.

CONTENTS

CHAPTER 1

 INTRODUCTION

    Document Structure
    New System Variables
    New System Services

CHAPTER 2

    HARDWARE

    Rom
    Ram
    Display

CHAPTER 3

    IDENTIFICATION BYTES

    Language-byte
    Model-byte
    Model-byte-2
    Version Number
    Identifying The LZ

CHAPTER 4

    WRITING APPLICATIONS

    Opl Applications
    Compatibility
    Running On 2 And 4 Line Machines
    New Commands And Functions
    Machine-code Applications
    Running On 2 And 4 Line Machines

CHAPTER 5

    DISPLAY MODES

    2-line Compatibility

    System Variables
        DPB_MODE
        DPA_SCRN
        DPB_NLIN
        DPB_WIDE
        DPB_BORD

    System Services
        DP$MSET
        DP$PVEW

CHAPTER 6

    UDG CHARACTERS

    Use Of UDGs

    System Services
        DP$UDG

CHAPTER 7

    THE UDG CLOCK

    Use of UDGs
    Starting And Stopping The Clock
    Updating The Clock

    System Variables
        DPB_CLOK
        DPB_CRED

    System Services
        DP$CSET
        DP$CPRN

CHAPTER 8

    MENUS

    System Variables
        MNB_CPTZ

    System Services
        MN$XDSP
        MN$1DSP
        MN$TITL

    Top Level Menu

CHAPTER 9

    DIARY AND MONTH

    System Variables
        DIB_1SLT
        DIB_AP

    System Services
        DI$ENTR

CHAPTER 10

    CALCULATOR

    System Services
        CA$ENTR

CHAPTER 11

    SYSTEM TIME

    System Variables
        TMB_24F

    System Services
        TI$ENTR
        TM$NDYS
        TM$WEEK
        TM$DNAM
        TM$MNAM
        TM$TSET

CHAPTER 12

    NOTEPAD

    Notepad Structure

    System Variables
        NTB_FLGS
        NTB_PSSW
        NTW_CLIN
        NTB_CPOS

    System Services
        NT$ENTR

CHAPTER 13

    WORLD

    System Services
        WL$ENTR

CHAPTER 14

    ALARM

    System Variables
        AMB_WRKD

    System Services
        AM$ENTR

CHAPTER 15

    PROG

    System Services
        LG$ENTR

CHAPTER 16

    XFILES

    System Services
        XF$ENTR
        XF$SORT

CHAPTER 17

    UTILS

    System Services
        XT$ENTR
        XT$BAR
        XT$DIRM

CHAPTER 18

    SWITCHING OFF

    System Services
        BT$TOFF

CHAPTER 19

    GENERAL UTILITIES

    System Services
        UT$CMPB
        UT$WILD
        UT$SORT

CHAPTER 20

    LIST FUNCTIONS

    System Services
        FN$SUM
        FN$MEAN
        FN$VAR
        FN$STD
        FN$MIN
        FN$MAX

CHAPTER 21

    TRIG FUNCTIONS 

    System Services
        FN$ASIN
        FN$ACOS

CHAPTER 22

    EDITOR

    System Services
        LG$EDIT
        TL$ZZMD

CHAPTER 23

    ERROR PRINTING

    System Services
        ER$PRNT

CHAPTER 24

    FILE HANDLING

    System Services
        FL$WPAR
        FL$WCAT
        FL$NCAT
        FL$WCPY
        FL$WDEL
        FL$WFND
        FL$FDEL
        FL$GETX
        FL$VALX

CHAPTER 25

    OPL TRANSLATOR

    System Services
        LN$XSTT

CHAPTER 26

    KEYBOARD

    Shift Exe
    Shift Space
    Shift Right-arrow

    System Variables
        KBB_SPEC

    System Services
        KB$CONK

CHAPTER 27

    FOREIGN LANGUAGES

    Language Selection On Cold Start
    Changing Language

    System Variables
        BTB_LANG
        XTB_COLD

    System Services
        TL$LSET

CHAPTER 28

    PASSWORDS

CHAPTER 29

    LZ64 RAM USAGE

CHAPTER 30

EXTENSIONS TO EXSISTING SYSTEM SERVICES

    DP$EMIT
    DP$VIEW
    MN$DISP
    ER$MESS
    LN$STRT
    UT$DISP
    TL$LSET
    TM$DAYV
    DP$SAVE AND DP$REST
    DV$BOOT
    RM$RUNP
    ED$EDIT / ED$EPOS

CHAPTER 31

    ADDITIONAL RECORD TYPES

CHAPTER 32

    RELEASE NOTES

    Version 4.2
    Version 4.3
    Version 4.4

Index Of New System Services


*******************************************************************************
CHAPTER 1    Introduction
*******************************************************************************

The LZ and LZ64 are the new Organiser II models which have a 4 line
by 20 character screen, are multi-lingual and offer many new facilities.

The operating system in the LZ(64) is fully back-compatible with the
standard Organiser II operating system 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.

*******************************************************************************
Document Structure

This document describes the LZ's extensions in detail and is intended
as a supplement to the main "Organiser II Technical Manual".

All new system services and variables are described in detail in the
appropriate section.

An index of all new system services is provided at the end.

*******************************************************************************
New System Variables

The new system variables cannot be accessed on 2-line machines with
the exception of the following variables which have been allocated
space which was reserved and will always be zero on 2-line machines:

    DPB_MODE     $2184 - display mode
    KBB_SPEC     $2185 - special key flags
    BTB_LANG     $2186 - language byte

*******************************************************************************
New System Services

The new system services have vector numbers from 129 to 179 inclusive.
They can only be used on LZ machines, if they are called on a 2-line
Organiser it will cause the machine to crash.  The user must use the
ROM identification bytes to check which machine the software is running
on.

Entry points to the top-level applications have been included as system
services named as XX$ENTR where XX is the name of the application
(e.g. DI$ENTR provides access to the diary functions).  Most of these
types of system service take a "function number" in the B register
to identify which function of the application to run.  For example
in DI$ENTR, B takes the following values:

    0 - initialise the diary.
    1 - enter the DIARY application.
    2 - search the diary (called from UTILS SEARCH).
    3 - enter the MONTH application.

Note that there is no checking of the B registers values, so ONLY
these values of B can be used or the machine will crash.

This is the correct way into the top-level applications from machine
code - do not search the main menu for the application and its address,
as its name changes in multi-lingual versions.

*******************************************************************************
CHAPTER 2    Hardware
*******************************************************************************

The hardware is basically the same as standard organiser II with the
following differences.

*******************************************************************************
Rom

Both the LZ and LZ64 have 64k of ROM.  The ROM from $8000 to $BFFF
is bank-switched in 3 banks of 16k and the ROM from $C000 to $FFFF
is fixed. (see appendix C of the LZ(64) programming manual). The bank-switching
is carried out by accessing the following addresses (reading or writing):

    $360    - Reset ROM/RAM to bank 0
    $3E0    - Select next ROM bank

Note that the operating system may switch ROM banks when any system
service is called and during interrupts.

*******************************************************************************
Ram

The model LZ has 32k of RAM and the LZ64 has 64k. The RAM from $4000
to $7FFF is bank switched in 3 banks of 16k and the RAM below $4000
is fixed. (see appendix C of the LZ(64) programming manual). The bank-switching
is carried out by accessing the following addresses (reading or writing):

    $360    - Reset ROM/RAM to bank 0
    $3A0    - Select next RAM bank


See chapter 29, LZ64 RAM USAGE for details of the use of the "extra"
32k of RAM.

*******************************************************************************
Display

The display on the LZ and LZ64 uses the same LCD drivers as on the
standard Organiser but is arranged as 4 lines by 20 characters.  The
control lines at addresses $180 and $181 still work in the same way
but note the arrangement of the LCD addresses (0-79) mapped onto the
screen:

     0  1  2  3  8  9 10 11 12 13 14 15 24 25 26 27 28 29 30 31

    40 41 42 43 48 49 50 51 52 53 54 55 64 65 66 67 68 69 70 71

     4  5  6  7 16 17 18 19 20 21 22 23 32 33 34 35 36 37 38 39

    44 45 46 47 56 57 58 59 60 61 62 63 72 73 74 75 76 77 78 79

The system service DP$EMIT maps each character printed to its correct
position but any applications which write directly to the LCD must
take account of the mapping.

The character set has been changed to accommodate foreign characters.
The characters from 0 to 127 remain the same except for character
92 which is changed to a "\" character.  Most characters from 128
to 255 have changed but some are left for compatibility, e.g. character
254 is left as a space to use as a blank "non-space" character.

To further maintain compatibility, the system service DP$EMIT will
translate any characters from $80 to $A0 inclusive into a space character
if the machine is running in "2-line compatibility mode".

As on the standard Organiser II there are 8 UDGS available, but note
that there is a new system service, DP$UDG, to define and read UDG's
correctly.

*******************************************************************************
CHAPTER 3    Identification Bytes
*******************************************************************************

There are 3 identification bytes which up to now have uniquely defined
each Organiser model.  They occupy the following addresses:

        $FFE7    - Language(s)-byte
        $FFE8    - Model-byte
        $FFE9    - Version number

The model-byte now contains a flag which, if set, means "look at model-byte-2"
which occupies the following address:

        $FFCB    - Model-byte-2

The above 4 bytes together will now uniquely identify all Organiser
models.

*******************************************************************************
Language-byte

ADDRESS:    $FFE7
VALUES:    $00    - English
           $01    - French
           $02    - German
           $80    - Eleven languages (English default)
           $81    - English, French, German (English default)

This was introduced in version 3.6 of the Organiser O.S.

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 will be added as new language variants are introduced.

Applications should look at the RAM language byte BTB_LANG to detect
which language any machine is running in (see chapter 27, foreign
languages).

*******************************************************************************
Model-byte

ADDRESS:    $FFE8
VALUES:    See below.

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.

BASE MODEL TYPE:-

    VALUE    MODEL    RAM SIZE    PROM SIZE
    0        CM       8K          32K
    1        XP(16)   16K         32K
    2        XP       32K         32K
    5        LP       64K         64K
    6        LZ       32K         64K
    7    - Expand to MODEL-BYTE-2


SPECIAL MODEL TYPE:-

Bits 7 to 4 indicate special models.
Bit 3 indicates - Expand to MODEL-BYTE-2.

If the base model type is 7, the base model will be given by the bottom
3 bits of MODEL-BYTE-2. If the special model type has bit 3 set, the
special model will be given by the top 5 bits of MODEL-BYTE-2. Note
that these two features are totally independent.

*******************************************************************************
Model-byte-2

ADDRESS:    $FFCB
VALUES:    See below.

This byte is split in the same way as the MODEL-BYTE with top 5 bits
for special flags and the bottom 3 bits for base model types.

Bit 7 set signifies LZ functionality.
Bit 6 set indicates foreign character LCD as appose to original LCD.
Bits 5,4 and 3 are reserved for extra special types.
Bottom 3 bits are reserved for future base model types.

*******************************************************************************
Version Number

ADDRESS:    $FFE9

The LZ version number was initially released at version 4.2, stored
as $42 (66 decimal). See also chapter 31, release notes.

*******************************************************************************
Identifying The LZ

It is important that machine-code applications software that uses
the features of the LZ operating system detects which machine it is
running on, otherwise it will crash when run on 2-line machines.

The LZ can be identified in either of two ways:

    1) If the variable DPB_MODE is set to 1, the machine is an LZ.
        However, if DPB_MODE is 0, the machine may be a 2-line machine
        or an LZ running in 2-line mode, see chapter 5,display modes.

    2) The MODEL-BYTE and MODEL-BYTE-2 can be examined.
        If bit 3 of $FFE8 is set and bit 7 of $FFCB is set the machine has
        an LZ operating system.  If bit 6 of $FFCB is set, the LCD is the
        foreign character LCD.

Hence the LZ has the following id bytes:-

        $FFE8:    $0E
        $FFCB:    $C0

and the LZ64 has the following id bytes:-

        $FFE8:    $0D
        $FFCB:    $C0

*******************************************************************************
CHAPTER 4    Writing Applications
*******************************************************************************
Opl Applications

OPL has been extended on the LZ. Some existing commands and functions
have been extended to use the 4 lines (e.g. AT 20,4, VIEW(4,A$) etc)
and some new commands and functions have been added.

The LZ is fully back-compatible with 2-line Organisers, so any existing
OPL programs will run exactly the same on the LZ as they do on the
CM or XP but will use 2 lines in the centre of the screen with a border
around.  This section describes how OPL applications can be written
which will run on both types of machine and will make use all 4 lines
when run on an LZ.

***** Compatibility *****

When OPL programs which have been translated on a 2-line Organiser
(CM, XP, etc) are run either from the TOP-LEVEL menu or under PROG
the machine is automatically put into "2-line compatibility mode"
(See chapter 5, display modes).

The mode in which the OPL program runs is determined by the FIRST
OPL PROCEDURE RUN.  Any subsequent OPL procedures which are loaded
will run in the same mode.

The OPL OBJECT CODE generated when translated on an LZ contains a
STOP code followed by a SINE code at the front of the procedure. Thus
the object code of all 4-line procedures will be two bytes longer
than the same procedure translated on a 2-line machine.  The STOP/SINE
configuration is used for 2 reasons:-

    1) The combination will identify the procedure as 4-line since it
       can never be generated on a 2-line Organiser.

    2) When run on a 2-line machine, the procedure will cause OPL to
       stop running, i.e. terminate the OPL program.

Note that LZ machines can translate procedures as though they were
translated on a 2-line Organiser using the "XTRAN" option in the PROG
EDITOR menu.

It follows from this that 2-line code can run in 4-line mode providing
the initial procedure is 4-line, but 4-line code can never run in
2-line mode.

***** Running On 2 And 4 Line Machines *****

To create an OPL application which will run on both types of machine
and make use of all 4 lines when run on an LZ, use the following method:

    1) The main procedure should be translated in 2-line mode and
       should contain the following code:

    LOCAL M%(2)
    M%(1)=$3F82 :REM OS DP$MSET
    M%(2)=$3900 :REM RTS
    IF PEEKB($FFE8) AND 8)=8 AND (PEEKB($FFCB) AND $80)=$80
      USR(ADDR(M%()),256) :REM switch to 4-line mode if LZ
    ENDIF

    This code will switch to 4-line mode if it is run on an LZ but will
    do nothing if run on a 2-line machine.

    2) Code which can be used on both 2 and 4 line machines (generally
       code that does not print to the screen or use LZ only features)
       should be put in subroutines and translated in 2-line mode.

    3) Code to print to the 2 line screen should be put in one procedure
       and code to print to the 4 line screen in another - translated
       in 2-line mode and 4-line mode respectively.

    4) The main code must read DPB_MODE (address $2184) to decide which
       OPL procedures to call to print in the correct mode.

For example the following program will print "HELLO" on the 2nd line
of a 2-line machine and on the 4th line of an LZ. It consists of the
following modules:

        MODULE        TRANSLATE MODE

        MAIN          2-LINE
        HELLO2        2-LINE
        HELLO4        4-LINE


    MAIN:
    LOCAL M%(2)
    M%(1)=$3F82 :REM OS DP$MSET
    M%(2)=$3900 :REM RTS
    IF PEEKB($FFE8) AND 8)=8 AND (PEEKB($FFCB) AND $80)=$80
      USR(ADDR(M%()),256) :REM switch to 4-line mode if LZ
    ENDIF
    IF PEEKB($2184)
      HELLO4: :REM call "HELLO4" if 4-line mode
    ELSE
      HELLO2: :REM else call "HELLO2"
    ENDIF
    GET


    HELLO4:
    AT 1,4 :PRINT "HELLO"


    HELLO2:
    AT 1,2 :PRINT "HELLO"


***** New Commands And Functions *****

The OPL commands and functions which have been added on the LZ and
are not available on the CM or XP are as follows:

    OFF x% - Turns the Organiser off for a limited time only.
    UDG - Defines a display character (user-defined graphic).

    COPYW - Copies any type of file with wild card matching.
    DELETEW - Deletes any type of file with wild card matching.

    CLOCK - Displays the "UDG CLOCK".
    MENUN - Displays the different types of menu.

    DIRW$ - Returns name of any type of file with wild card matching.
    FINDW - Like FIND but allows the use of wild cards.

    ACOS - Returns the arc cosine of a number.
    ASIN - Returns the arc sine of a number.

    MAX - Returns the greatest item in a list.
    MIN - Returns the smallest item in a list.
    MEAN - Returns the mean of items in a list.
    STD - Returns the standard deviation of items in a list.
    SUM - Returns the sum of items in a list.
    VAR - Returns the variance of items in a list.

    DAYS - Returns the number of days since 01/01/1900
    DAYNAME$ - Converts 1 - 7 to the day of the week.
    DOW - Returns the day a date falls on as a number 1 - 7.
    MONTH$ - Converts 1 - 12 to the month.
    WEEK - Returns the week number a date falls in.

Note that XTRAN will give an error if used to translate any of
the above commands.

*******************************************************************************
Machine-code Applications

Devices are booted on cold start before asking for a language and
again afterwards when the language has been selected to enable the
device to switch languages. This feature can be disabled (see chapter
27, foreign languages).

***** Running On 2 And 4 Line Machines *****

All current machine code applications will run on the LZ as they
stand but will automatically be put into "2-line compatibility mode"
as soon as anything is printed to the screen.

There are 3 methods by which machine code applications can be run:

    1) Booting (running install and remove vectors).
    2) OPL Language extensions (running lang vector).
    3) From the top-level menu.

Whichever method is used, the LZ will switch to 2-line mode before
anything is printed and will switch back to 4-line mode when returning.

The device itself must put the machine into 4-line mode if required,
by calling system service DP$MSET.

Machine code applications which print to the screen should use the
following method to implement 2-line and LZ compatible software. Whenever
the application is entered, from either of the above 3 methods, the
following should be carried out:

    1) Before calling any system services, check the value of DPB_MODE.
       If DPB_MODE = 0, take no further action and run in 2-line mode.

    2) If DPB_MODE = 1, call DP$MSET prevent the operating system switching
       to 2-line mode.

Note that machine code applications can simply check DPB_MODE rather
than looking at the ROM id bytes because the mode will not change
until anything is printed to the screen. However, OPL applications
will have already been put into 2-line mode by the time they are running,
so they must check the ROM id.

For example the following procedure will print "HELLO" on the 2nd
line of a 2-line machine and on the 4th line of an LZ:

    LDA    A,DPB_MODE
    BEQ    1$        ;branch to run in 2-line mode
    OS    DP$MSET        ;set to 4-line mode A=1
    OS    UT$DISP
    .BYTE    12,23        ;clear screen and goto 4th line
    .ASCIZ    "HELLO"
    RTS

1$:    OS    UT$DISP
    .BYTE    12,10        ;clear screen and goto 2nd line
    .ASCIZ    "HELLO"
    RTS

*******************************************************************************
CHAPTER 5    Display Modes
*******************************************************************************

2-line Compatibility
********************

The LZ maintains compatibility with 2-line Organisers by emulating
the 2 line screen.

Thus, there are two modes of operation:

    1) 4-line mode.
    2) 2-line compatibility mode.

To simplify the writing of 2-line/4-line applications, variables are
provided for the address of the screen, the mode, the number of lines
and the width of the screen which are valid in either mode.

The system service DP$MSET is provided to switch between modes.

Note also that existing bootable applications are automatically put
into 2-line mode if they print to the screen (see chapter 4).

In 2-line compatibility mode all existing applications should work
exactly as though they are running on a 2-line Organiser.  The same
screen buffer (DPT_TLIN) is used when in this mode.

*******************************************************************************
System Variables

The following system variables control the display mode and the border
character.

***** DPB_MODE *****

ADDRESS:    $2184
VALUES:    0 for 2-line mode.
        1 for 4-line mode.

DPB_MODE shows the display mode that is currently in operation. It
is set by the operating system service DP$MSET. It can be read at
any time but should not be written to directly (DP$MSET must be used).

***** DPA_SCRN *****

ADDRESS:    $2090
VALUES:    DPT_TLIN in 2-line mode.
        DPT_4LIN in 4-line mode.

DPA_SCRN contains the address of the current screen buffer. It is
set by the operating system service DP$MSET. When in 2-line mode,
it contains the address of DPT_TLIN - the 2-line screen buffer at
the same memory location as on 2-line Organisers (for compatibility)
When in 4-line mode it contains the address of DPT_4LIN - the new
80 character 4-line screen buffer. It can be read at any time but
should not be written to directly (DP$MSET must be used).

***** DPB_NLIN *****

ADDRESS:    $2092
VALUES:    2 in 2-line mode.
        4 in 4-line mode.

DPB_NLIN contains the number of screen lines in the current display
mode. It is set by the operating system service DP$MSET. It can be
read at any time but should not be written to directly (DP$MSET must
be used).

***** DPB_WIDE *****

ADDRESS:    $2093
VALUES:    16 in 2-line mode.
        20 in 4-line mode.

DPT_WIDE contains the screen width in the current display mode. It
is set by the operating system service DP$MSET. It can be read at
any time but should not be written to directly (DP$MSET must be used).

***** DPB_BORD *****

ADDRESS:    $2099
VALUES:    0 - $FF
DEFAULT:    $F5

DPB_BORD contains the character used for the border when in 2-line
compatibility mode.  It is initialised on 'cold-start' and in RESET
to $F5 (a chequered square). It can be read or written to at any time.

*******************************************************************************
System Services

***** DP$MSET *****

VECTOR NUMBER.    130
INPUT PARAMETERS:    A register - mode required: 0 for 2-line,
1 for 4-line mode.
                Bit 7 set specifies leave clock alone.
OUTPUT VALUES:    A register - previous mode.
PRESERVES:    B,X registers.


DESCRIPTION

Sets the Operating System into 2 or 4 line mode.

The following is always carried out:-

1) If the top bit of the A register is clear, the UDG CLOCK is switched off.
2) The variable DPB_MCHK is cleared.
3) END if the mode requested is the same as the current mode.
4) The screen is initialised for the mode selected:-

    2-line:    clear 16 character by 2 line window with border.
    4-line:    clear entire 4-line screen.

5) The variables DPA_SCRN, DPB_NLIN, DPB_WIDE are initialised.

EXAMPLE

Machine-code applications for 2 and 4 line machines can use the following
code:-

        LDA     A,DPB_MODE
        BEQ     1$               ;branch to run in 2-line mode
        OS      DP$MSET          ;set to 4-line mode A=1

        ;PUT 4-LINE CODE HERE

        RTS

1$:     ;PUT 2-LINE CODE HERE

        RTS

ERRORS
        None.

BUGS
        None.


***** DP$PVEW *****

VECTOR NUMBER:    163
INPUT PARAMETERS:    A register - Bit 7 set for routine to exit
on arrow keys.
            B register - Length of string to view.
            X register - Address of string to view.
            UTW_S0  - Time delay before scrolling begins.
OUTPUT VALUES:    None.


DESCRIPTION

A partial view routine. Works exactly like DP$VIEW but at the current
cursor position given by DPB_CPOS.  Any characters before the cursor
will not scroll but the string at X will be displayed scrolling on
the remainder of the line.


EXAMPLE

This routine is used, for example, in CALC on the LZ.


ERRORS
        None.

BUGS
        None.

*******************************************************************************
CHAPTER 6    UDG Characters
*******************************************************************************

Use Of UDGs
***********

The LZ uses the same display drivers as the 2-line Organiser, hence
there are still only 8 UDGs available.  They can be defined in the
same way as on the 2-line Organiser but a new system service DP$UDG
has been provided to simplify the operation.  There is also the OPL
extension "UDG" which will define UDG characters.

In the LZ, UDGs are used for the following:-

  *  Icons - UDG 0
  *  The UDG clock - UDGs 1,3,4,5,6,7
  *  The underscore characters used in the title lines - UDG 2
  *  The dotted lines - UDG 2
  *  The diary "week at a view" - ALL 8 UDGs.
  *  The bar graph in "Info" - ALL 8 UDGs.

Note that the UDG CLOCK uses UDG 1 for the am/pm indicator, so when
24-hour mode is set, UDG 1 will not be used.

Note also that the 'high' and 'low' dotted lines both use UDG 2 and
therefore cannot appear on the screen at the same time as the title
line.

Applications can use all 8 UDGs since they are always re-defined by
the operating system before use.

*******************************************************************************
System Services

***** DP$UDG *****

VECTOR NUMBER.    133
INPUT PARAMETERS:    A register - 0 for 8 byte pattern, 1 for 5
bytes.
                Bit 7 set to READ (8 bytes always).
            B register - The UDG to define (0 - 7).
            X register - points to the 8 or 5 byte pattern.
OUTPUT VALUES:    None.


DESCRIPTION

Defines or reads a UDG.
If the top bit of A is clear - Defines UDG B with the pattern at X.
UDGs are 5 pixels wide by 8 pixels high. If the A reg is 0, the first
byte at X is the top line of the UDG and bits 4 to 0 define the pattern
from left to right. To allow UDGs to be stored in 5 bytes instead
of 8 the A reg should be set to 1.  Then the first byte at X defines
the left hand edge of the udg with bit 7 as the top pixel.

If top bit of A is set - Reads UDG B into buffer at X (using 8 bytes
always).


Note that interrupts are disabled in DP$UDG.


EXAMPLE

1) Defines UDG 0 as the underlined bell icon.


        CLR     B
        CLR     A               ;use 8 bytes
        LDX     #UDG
        OS      DP$UDG
        RTS


UDG:    .BYTE   $04,$0E,$0E,$1F,$1F,$04,$00,$1F

2) Define the same UDG in 5 bytes.

        CLR     B
        LDA     A,#1            ;use 5 bytes
        LDX     #UDG
        OS      DP$UDG
        RTS


UDG:    .BYTE   $19,$79,$fd,$79,$19


ERRORS
    None.

*******************************************************************************
CHAPTER 7    The UDG Clock
*******************************************************************************

Use of UDGs
***********

The UDG clock uses UDGs 1,3,4,5,6,7 in the following manner.

EXAMPLE TIMES:
        _  9  :  3  0  a
        1  2  :  4  5  p
        1  2  _  4  5  p

UDG USED:        3  4  5  6  7  1

The flashing colon is achieved by redefining UDG 5 every 1/2 second
in the keyboard interrupt.

*******************************************************************************
Starting And Stopping The Clock

The system service DP$CSET, can print the clock anywhere on the screen
and will initialise the updating of the clock every 1/2 second.

DP$CSET can also stop the clock by preventing the updating but the
UDGs will remain on the screen until they are overwritten by printing.

*******************************************************************************
Updating The Clock

The clock is updated in the keyboard interrupt routine by calling
DP$CPRN. Every 1/2 second UDG 5 is re-defined to achieve the flashing
colon and every time the minutes change, all UDGs used for the clock
are re-defined.

Occasionally, the clock will stop flashing, e.g. when printing. This
is because the keyboard interrupts have been disabled momentarily.
The clock will not, of course, lose any time since it always gets
the time from the system clock.

*******************************************************************************
System Variables

The following system variables control the UDG clock.

***** DPB_CLOK *****

ADDRESS:    $2095
VALUES:    0 - 74, bit 7 set or clr.


DPB_CLOK stores the position of the left most character of the 6 character
UDG clock.  If bit 7 is set the clock will not be updated (i.e. it is
off). It is set by the operating system service DP$CSET. It can be
read at any time but should not be written to directly (DP$CSET must
be used).

***** DPB_CRED *****

ADDRESS:    $2096
VALUES:    0 - 9, bit 7 set or clr.


DPB_CRED is the "clock ready" flag, it is used to time the 1/2 second
flashing of the colon. It counts down from 9 to 0 and the top bit
is toggled for the flashing colon.  If bit 7 is set, the ":" is printed,
otherwise just an underline character.

*******************************************************************************
System Services

***** DP$CSET *****

VECTOR NUMBER:    131
INPUT PARAMETERS:    B register - position of clock on screen.
                Bit 7 set to switch clock off.
OUTPUT VALUES:    B register - previous clock position and status.


DESCRIPTION

Sets the clock-display status.

The B register specifies where on the screen the clock will appear
as a position 0 to 74 (max 26 in 2 line mode). If the top bit of B
is set, no clock will be displayed. The clock is printed when DP$CSET
is called and is updated in the keyboard interrupt. The interrupt
just re-defines the UDGs and does not write to the screen.

The current screen status (cursor position etc) is always preserved.

Note that 5 UDGs (chars 3 to 7) are used to print the underlined clock
and 6 if in 12 hour mode - UDG 1 is used for am/pm indicator and will
overwrite any UDGs previously defined.

The clock is always right justified in a field of 6 characters (a
UDG "_" is used to justify).

EXAMPLE

Print a title line with the clock in the top right-hand corner. UDG
0 has been defined as an icon, UDG 1 as an underscore character.


    LDX    #TOP_TITLE
    PSHX
    OS    UT$DISP
    .BYTE    12
    .ASCIZ    "%s"        ;print top-line
    LDA    B,#15        ;UDG clock in top-right hand corner
    OS    DP$CSET        ;set to clock mode
    PSH    B
    OS    KB$GETK        ;wait for key (clock will be updated)
    PUL    B
    OS    DP$CSET        ;restore clock status
    RTS

TOP_TITLE:
    .byte    20
    .byte    0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1


ERRORS
    None.

***** DP$CPRN *****

VECTOR NUMBER:    132
INPUT PARAMETERS:    A register - 0 to define UDG 5 only.
OUTPUT VALUES:    None.
PRESERVES:    All scratch registers (UTW_S0 - UTW_S5).


DESCRIPTION

Re-defines the UDGs used for the clock as the current system time.
If the A register is 0, just UDG 5 is defined (the flashing colon).
Defines UDG 5 as ":" if the top bit of DPB_CRED is set, otherwise
defines UDG 5 as "_".

The screen status (cursor position etc) is always preserved.

EXAMPLE


    OS    DP$CPRN
    RTS


ERRORS
    None.

*******************************************************************************
CHAPTER 8    Menus
*******************************************************************************

The structure of menus is the same in the LZ operating system as in
the XP, however they can now be displayed on the screen in a variety
of ways using the system services below.

All menus (except 1 line menus) are now aligned in 3 columns. However
if there is any item greater than 6 characters long, 2 columns will
be used.  Aligning in columns uses more space in RTT_BF where the
menu is constructed, so to maintain compatibility, if an aligned menu
will not fit, the menu reverts back to a single spaced menu automatically.

All menu items appear on the screen capitalized (but not in 2-line
mode - for compatibility) but this can be over-ridden by writing to
MNB_CPTZ.

*******************************************************************************
System Variables

***** MNB_CPTZ *****

ADDRESS:    $209C
VALUES:    0 or 1.
DEFAULT:    0.


If this byte is set to 1, the entries in the menu will not be capitalized,
i.e. they will appear as they are stored.  Once set, ALL menus will
appear as they are stored until the machine is reset or the byte restored
to 0. This flag is used by the operating system in the FORMAT menu
"PACK B: PACK C:".

*******************************************************************************
System Services

***** MN$XDSP *****

VECTOR NUMBER:    134
INPUT PARAMETERS:    D register - Terminating bit-mask.
            X register - Address of menu-list.
OUTPUT VALUES:    A register - Flag to indicate the type of contents
in the X register.
                If A=0, X has the address of the routine
                    associated with the item selected,
                else,  X points to the name of the selected
                    item in the menu-list.
            X register - Depends on value of A register.
            B register - Terminating key press.
            UTW_S0   - Number of the menu item selected (0 for first item).

DESCRIPTION

Exactly the same as MN$DISP except that text already on the screen
is treated as a title with the menu underneath (starting on the next
clear line).  If more the 3 lines of text are on the screen, the text
will be truncated, and the last line used for the menu.

Note that in 4-line mode, menus are now aligned in three columns unless
there are items longer than 6 characters in which case it switches
to 2 columns.

EXAMPLE

Displays a title on the top line with the menu underneath.

    OS    UT$CDSP
    .ASCIZ    "==== MAIN MENU ====="
    LDX    #MENU_LIST        ; Point to the menu-list
    LDD    #$1000            ; Terminate on EXE only
    OS    MN$XDSP            ; Call the service
    RTS

MENU_LIST:
    .ASCIC    "FIND"
    .WORD    TL_FIND
    .ASCIC    "SAVE"
    .WORD    TL_SAVE

    ...etc...

    .BYTE    0


ERRORS
    ER_RT_ME - menu error.

BUGS

If the D register is passed as 0 then the routine will never exit
as there will be no valid terminating character. Also note that this
routine puts the keyboard state into alpha shift.


***** MN$1DSP *****

VECTOR NUMBER:    135
INPUT PARAMETERS:    D register - Terminating bit-mask.
            X register - Address of menu-list.
OUTPUT VALUES:    A register - Flag to indicate the type of contents
in the X register.
                If A=0, X has the address of the routine
                    associated with the item selected,
                else,  X points to the name of the selected
                    item in the menu-list.
            X register - Depends on value of A register.
            B register - Terminating key press.
            UTW_S0  - Number of the menu item selected (0 for first item).


DESCRIPTION

Exactly the same as MN$DISP except that the menu is displayed in one
line only and scrolls horizontally. The remaining 3 lines of the screen
are left intact. The line which the menu is displayed will be the
line containing the cursor in its current position, DPB_CPOS.

It is suggested that the following DP$EMIT control codes be used to
position the cursor:-

24 - prints .... on 2nd line and puts cursor on top line.
25 - prints .... on 3rd line and puts cursor on bottom line.

Note that DPB_CPOS should not be poked directly.

EXAMPLE

Displays a menu on the top-line only, scrolling horizontally.


    OS    UT$DISP
    .BYTE    24,0        ;position cursor on top line
    LDX    #MENU_LIST    ;point to the menu-list
    LDD    #$1000        ;terminate on EXE only
    OS    MN$1DSP        ;call the service
    RTS

MENU_LIST:
    .ASCIC    "FIND"
    .WORD    TL_FIND
    .ASCIC    "SAVE"
    .WORD    TL_SAVE

    ...etc...

    .BYTE    0


ERRORS
    ER_RT_ME - menu error.

BUGS

If the D register is passed as 0 then the routine will never exit
as there will be no valid terminating character. Also note that this
routine puts the keyboard state into alpha shift.

***** MN$TITL *****

VECTOR NUMBER:    136
INPUT PARAMETERS:    D register - Terminating bit-mask.
            X register - Address of menu-list.
OUTPUT VALUES:    A register - Flag to indicate the type of contents
in the X register.
                If A=0, X has the address of the routine
                    associated with the item selected,
                else,  X points to the name of the selected
                    item in the menu-list.
            X register - Depends on value of A register.
            B register - Terminating key press.
            UTW_S0  - Number of the menu item selected (0 for first item).


DESCRIPTION

Exactly the same as MN$DISP except that the top line is used to display
an icon on the left and a running digital clock on the right.

UDG 0 is always displayed in the top left hand corner of the display.

EXAMPLE

Displays a menu like the top-level menu.


    CLR    A
    CLR    B            ;define udg 0
    LDX    #MAIN_ICON
    OS    DP$UDG
    LDX    #MENU_LIST        ;Point to the menu-list
    LDD    #$1000            ;Terminate on EXE only
    OS    MN$TITL            ;Call the service
    RTS

MAIN_ICON:
    .BYTE    $0F,$09,$0F,$0F,$0F,$0F,$00,$0F

MENU_LIST:
    .ASCIC    "FIND"
    .WORD    TL_FIND
    .ASCIC    "SAVE"
    .WORD    TL_SAVE

    ...etc...

    .BYTE    0


ERRORS
    ER_RT_ME - menu error.

BUGS

If the D register is passed as 0 then the routine will never exit
as there will be no valid terminating character. Also note that this
routine puts the keyboard state into alpha shift.

*******************************************************************************
Top Level Menu

The top level menu works exactly the same as in the standard Organiser
but has been extended to allow the names of "Notes" and "Files" to
be inserted as well as the names of "Opl" procedures.

This is done by using 0001 and 0002 as the execution addresses for
Notes and Files respectively (0000 is still for Opl).

Programs which search the top-level menu for items such as TIME, so
that they can call the time application will still work on the LZ,
however this practice is not recommended as the LZ is multi-lingual.
For convenience, the LZ provides system services as entry points for
all top-level functions (see chapter 1, Introduction).

*******************************************************************************
CHAPTER 9    Diary And Month
*******************************************************************************

The LZ diary is stored in the same cell and in almost exactly the
same format as the CM/XP diary. The only change is that an extra byte
is added at the end of each entry, to specify the duration of the
entry (in quarter hours). The length byte also takes this duration
byte into account, so it now contains the length of the entry plus
one.

EXAMPLE

    Mon  8 May 1989 Wk19
     6:00a <Free>
     5:15p ABCDEF
     5:45p <Free>


If an alarm is set for 15 minutes early, the bytes are:

    $07    length of "ABCDEF" plus one
    $59    year 1989
    $04    month MAY
    $07    day 8
    $11    hour 17
    $0F    minutes 15
    $10    alarm 15 minutes early
    6 bytes "ABCDEF"
    $02    duration 30 minutes

and then, the next entry or 0 for end-of-diary.

Notice that, as before, year month and day "start" from 0. An "alarm"
byte of 0 means "no alarm"; otherwise it is the number of minutes
to ring early, plus one.

Because the length byte "includes" the extra duration byte, you can
use the same code to scan through the diary as on the CM/XP, although
your programs must then handle the duration byte specially. The length
byte therefore can have values from 2 to 65. Note that Psion's "Diary
Link" product (versions 1.0 or 1.1) should NOT be used on models LZ/LZ64,
because it knows nothing of duration bytes. If you do use it to load
a diary from a PC, curious things may happen when you enter the diary,
such as entries disappearing or having impossible times.

Other Changes

Times are displayed in 12 or 24 hour format, as specified by the user
when setting the system time.

As well as chronological order being required, and no two entries
having the same time, it is also essential that they do not overlap
because of their durations. They may, however, meet exactly. No entry
must pass midnight (p.m.) owing to its duration.

The time must be in the year range 1900-2155 with minutes 0, 15, 30
or 45. Note that all dates still "wrap around", from 2155 to 1900
and vice versa.

The maximum length of a "Find String" in the "Find" option is 30,
not 32.

The diary is no longer saved (using the "Save" option) as a block
file of type $82, but instead as an ordinary data file. Each entry
is saved as a separate record - the previous example would be:

    1989050817150216
    ABCDEF

The first field specifies the date of the entry (1989, 05, 08, for
8th May 1989), the time (17 15, for 5:15pm), the duration (02) and
the alarm byte (16, for 15 minutes before - again, 00 would mean "no
alarm"). The second field is the text of the entry. The order of things
in the first field, and the use of zeroes where necessary to keep
things the same length (e.g. "02" for a duration of 2) make the file
easy to sort in OPL, or otherwise. Note, though, that the "Restore"
option in the diary will restore entries in any order from a file.
The "Xrestore" option can be used to load a CM/XP diary from a pak,
in which case each entry is given a duration of 2 (=30 minutes). Note
that because a saved record can be edited or even created by a user,
the year, month and day sections start from 1, not 0 - e.g., the 1st
of the month is saved as "01", not "00".

You can not as yet interchange diaries with Sidekick on a PC, as versions
1.1 and below of Diary Link should not be used with the LZ/LZ64.

The UDGs used by the diary are:

    high week view arrow: 0
    low week view arrow: 1
    bell symbol in day page: 3
    four week view boxes: 4-7

*******************************************************************************
System Variables

Four bytes used in the "Setup" option in the diary are available outside
the diary.

***** DIB_1SLT *****

ADDRESS:    $20A9
VALUES:    1 - 96, see below

This is the address of three bytes which store the boundaries between
the four WEEK VIEW "slots". They are stored in quarter-hours, so e.g.
a value of 4 would mean 1:00am.

The three bytes, though contiguous, can be referenced by the separate
names DIB_1SLT, DIB_2SLT and DIB_3SLT. This diagram shows how a day
is divided into 4 slots IN THE WEEK VIEW:

    0 (midnight a.m.)        Slot 1 starts
    DIB_1SLT        Slot 1 ends/slot 2 starts
    DIB_2SLT        Slot 2 ends/slot 3 starts
    DIB_3SLT        Slot 3 ends/slot 4 starts
    96 (midnight p.m.)        Slot 4 ends

The maximum value for any of the three is 96 (midnight pm). DIB_1SLT
must be 1 or higher; DIB_2SLT must be higher than DIB_1SLT, and DIB_3SLT
higher than DIB_2SLT, with the exception that if DIB_3SLT is set to
96, it is then legal to set DIB_2SLT to 96 (and then, DIB_1SLT could
be set to 96 also). Setting the start time of a slot to 96 disables
that slot, and the flashing arrow in the week view will not move down
onto that slot.

***** DIB_AP *****

ADDRESS:    $20AC
VALUES:    0 or non-zero.


If this byte is not zero, alarm prompts are enabled in the diary and
whenever the user types an entry and set its time so that its date/
start time is greater than the current system time, an "Alarm? Y/N"
prompt is given. If this byte is set to zero, the prompt will not
be given. This feature is provided for users who rarely or never use
alarms in the diary, and who don't want to have to type "N" after
each entry.

*******************************************************************************
System Services

***** DI$ENTR *****

VECTOR NUMBER:    167
INPUT PARAMETERS:    B register - Function number; 0, 1, 2 or 3.


DESCRIPTION

This is the correct way into the diary from machine code - do not
search the main menu for "Diary" and its address, as its name changes
in multi-lingual versions.

All four functions begin by enabling SHIFT-EXE, clearing the diary's
paste buffer, setting the time in the diary to the system time and
defining the diary UDGs. They all end by disabling the SHIFT-EXE key.

The following functions are available:

Function 0 - Initialise diary. This is called on cold booting
the LZ. It clears
the diary (shrinks the cell to 1 byte length and writes a 0 in it)
and sets the "Setup" bytes to their default values (DIB_1SLT=48, DIB_2SLT=56,
DIB_3SLT=72, DIB_AP=non-zero).

Function 1 - Call the diary as from the
top-level menu option "Diary". This
enters the week view initially.

Function 2 - Search current diary for a given string.
This is called by the
"Search" option on the "Utils" menu. The find string should be in
RTT_FF. If an entry matches it will be printed on the bottom 2 lines
of the screen, and the user can press MODE to enter the diary in page
mode at this entry, EXE to search for the next match, or ON/CLEAR
to abort the search.

Output Values:    C set: The search went past end of diary.
            C clear, B=0: ON/CLR pressed, search aborted.
            C clear, B=1: MODE pressed, diary entered, then left.

Function 3 - Display the monthly calendar, as
from the top-level menu option
"Month". This will have the same menu available as in the week view,
and you can enter the day page with EXE.

ERRORS
    None.

*******************************************************************************
CHAPTER 10    Calculator
*******************************************************************************

The calculator in the LZ works in the same way as the standard Organiser
calculator but note the following:-

  *  If an OPL procedure is called from CALC, the screen is not
cleared automatically (as it is when run from PROG).

  *  If an OPL procedure is called from CALC, it is always run
in 4-line mode even if it was translated as a 2-line procedure.

*******************************************************************************
System Services

One system service is provided for calling the calculator, but note
that it must not be called from within an OPL procedure unless all
variables used by OPL are preserved.

***** CA$ENTR *****

VECTOR NUMBER:    160
INPUT PARAMETERS:    None.
OUTPUT VALUES:    None.


DESCRIPTION

Provides an entry point to the calculator exactly like selecting CALC
in the top-level menu.

Note that it must not be called from within an OPL procedure, since
OPL is not re-entrant unless all its variables are preserved.

EXAMPLE

    OS    CA$ENTR        ;Call the calculator
    RTS

ERRORS
    None.

*******************************************************************************
CHAPTER 11    System Time
********************************************************************************

The system time on the LZ is stored in the same 6 bytes as on the
standard Organiser however the range of values for TMB_YEAR has been
extended to 0 - 255 for the years 1900 - 2155 respectively.

The time stored always represents G.M.T., so the world times and daylight-saving
are calculated as offsets from this.

A system variable is provided for setting 12/24 hour clock and daylight-saving
flags and a system service is provided as an entry point for TIME.

*******************************************************************************
System Variables

***** TMB_24F *****

ADDRESS:    $20A6
VALUES:    Bits 7 and 0 only are used.
        All other bits are reserved.

TMB_24F stores 2 flags:-

  *  Bit 7 is set for daylight-saving ON, clear for OFF.
  *  Bit 0 is set for 24 hour mode, clear for 12 hour mode.

These flags can be read or written to at any time.

*******************************************************************************
System Services

***** TI$ENTR *****

VECTOR NUMBER:    164
INPUT PARAMETERS:    B register - Function number 0 or 1.
OUTPUT VALUES:    None.


DESCRIPTION

Provides an entry point to the TIME application.

There are two functions available:

Function 0 - Initialise. Actually does nothing!
Function 1 - Call the TIME application as from the top-level menu.

EXAMPLE

    LDA    B,#1        ;select function 1
    OS    TI$ENTR        ;run the time application
    RTS


ERRORS
    None.


***** TM$NDYS *****

VECTOR NUMBER:    149
INPUT PARAMETERS:    X register - Address of 3 byte date.
OUTPUT VALUES:    B register - MSB of result.
            X register - LSB's of result.
            If the date is invalid, carry flag is set.
PRESERVES:    A register.


DESCRIPTION

Returns the number of days since 01/01/1900 (if the date passed is
01/01/1900, the routine will return 0).

The X register points to a 3 byte date containing YEAR:MONTH:DAY in
the following ranges:

    YEAR:    0 - 255
    MONTH:    0 - 11
    DAY:    0 - 28,29,30 or 31

The result is returned in the B,X registers (B has the MSB).

Works from 01/01/1900 to 31/12/2155.

If an invalid date is passed, the carry flag will be set.

EXAMPLE

Calculates the number of days from 1st Jan 1900 to 25th Dec 1988.

    LDX    #DATE        ;point to 3 byte date
    OS    TM$NDYS
    BCS    BAD_DATE        ;branch if invalid date
    STA    B,HDAYS
    STX    LDAYS        ;store number of days
    RTS

DATE:    .BYTE    88        ;year 1988
    .BYTE    11        ;month december
    .BYTE    24        ;25th day


ERRORS
    None, just C set if date is invalid.


***** TM$WEEK *****

VECTOR NUMBER:    150
INPUT PARAMETERS:    X register - Address of 3 byte date.
OUTPUT VALUES:    B register - Week number (0 to 52).
            If the date is invalid, carry flag is set.
PRESERVES:    X,A registers.


DESCRIPTION

Returns the week number of the supplied date. The first MONDAY of
the year starts WEEK 1 which is returned as 0. Any dates before this
MONDAY are in the last week of the previous year.

Applications (e.g. the DIARY convert the week number from 0-52 to 1-53.

The X register points to a 3 byte date containing YEAR:MONTH:DAY in
the following ranges:

    YEAR:    0 - 255
    MONTH:    0 - 11
    DAY:    0 - 28,29,30 or 31

The result is returned in the B register, the 1st week is 0.

Works from 01/01/1900 to 31/12/2155.

EXAMPLE

Returns the "week number - 1" for 25th Dec 1988.

    LDX    #DATE        ;point to 3 byte date
    OS    TM$WEEK
    BCS    BAD_DATE    ;branch if invalid date
    STA    B,WEEK        ;store week number
    RTS

DATE:    .BYTE    88        ;year 1988
    .BYTE    11        ;month december
    .BYTE    24        ;25th day


ERRORS
    None, just C set if date is invalid.


***** TM$DNAM *****

VECTOR NUMBER:    151
INPUT PARAMETERS:    B register - Day of the week 0 - 6 (0 is Monday).
OUTPUT VALUES:    X register - Points to the day name string.


DESCRIPTION

Returns X as the address of the 3 letter day name for the day of the
week contained in the B register. Day is in current language selected.
Note that the day name will be in capitals.

EXAMPLE

Displays the 3 letter name for Sunday:

    LDA    B,#6        ;Sunday
    OS    TM$DNAM
    LDA    B,#3        ;name is always 3 bytes long
    OS    DP$PRNT        ;print the day name on the screen
    RTS

ERRORS
    None.

BUGS
    If the B register is not in the range 0 - 6, garbage will be returned.


***** TM$MNAM *****

VECTOR NUMBER:    170
INPUT PARAMETERS:    B register - Month 0 - 11 (0 is Jan).
OUTPUT VALUES:    X register - Points to the month name string.


DESCRIPTION

Returns X as the address of the 3 letter month name for the month
contained in the B register. Month is in current language selected.
Note that the month name will be capitalized.

EXAMPLE

Displays the 3 letter name for December:

    LDA    B,#11        ;December     OS    TM$MNAM
    LDA    B,#3        ;name is always 3 bytes long
    OS    DP$PRNT        ;print the month name on the screen
    RTS

ERRORS
    None.

BUGS
    If the B register is not in the range 0 - 11, garbage will be returned.


***** TM$TSET *****

VECTOR NUMBER:    179
INPUT PARAMETERS:    X register - Points to 6 byte date and time.
OUTPUT VALUES:    None.


DESCRIPTION

Sets the system time to the time pointed to by the X register. The
time cannot be simply poked into the system time variables since
an NMI may be updating the time.

EXAMPLE

Set the system time to 25th December 1988 at 09.30:00am.

    LDX    #TIME        ;point to 6 byte time to be set
    OS    TM$TSET        ;set the time     RTS

TIME:    .BYTE    88        ;year 1988
    .BYTE    11        ;month December
    .BYTE    24        ;day 25th
    .BYTE    9        ;hour 9
    .BYTE    30        ;minutes 30
    .BYTE    00        ;seconds 0

ERRORS
    None.

*******************************************************************************
CHAPTER 12    Notepad
*******************************************************************************

This chapter provides the information necessary to create a notepad
in memory and invoke the notepad editor as called from NOTES or a
named notepad in the top level menu or to generate a notepad on another
computer that can be saved to a datapak with the notepad file type
for loading from the editor.

The Notepad uses the same editor as is used to edit OPL programs.
This editor can be invoked directly by calling the system service
LG$EDIT (see chapter 22, editor).

*******************************************************************************
Notepad Structure

The Notepad text is stored in allocator cell 16 (defined as NOTECELL)
in exactly the same format as OPL source procedures (see main Organiser
II Technical Manual). On cold boot, the notepad cell is initialised
to contain the name "Notepad:" and system variables (see below) are
initialised.

The cell is structured as follows:

    a leading word specifying the length of the rest of the cell
    1-8 byte ascii name of notepad
    a colon to terminate the name
    an optional binary 0 byte to terminate the name
    ascii lines of notepad text, each line terminated by binary 0 byte

Each line has a maximum of 255 bytes including the 0 (these bytes
are encrypted when not in the editor if a password has been set).

Note that although the notepad name and colon are not editable, if
the optional 0 is not included then the first text line INCLUDING
THE NAME has a maximum of 255 bytes. The bytes after the colon can
be edited. A line consisting only of the terminating 0 represents
a blank line. The notepad can have any number of lines up to the capacity
of memory.

If the cell does not have this structure, the editor may display the
"PACK READ" error as if a corrupted notepad has been loaded from a
datapak or may produce unexpected results.

The notepad is saved onto a pak as a block body file of type 87 (defined
as BNOTTYP), and has the same structure as a saved OPL procedure with
object but instead of the Object Code (OCODE) bytes, notepad header
information is stored. Following the header, the file has the same
structure as the notepad cell as described above. The OCODE cell is
in fact used to hold the header information prior to saving to pak
and is zeroed after saving.

The header structure is:

    1 word length of Header information
    1 byte flags for notepad
        bit7 - true if numbered
        bit3 - true if on/clear exits editor
        bit2 - true if prompt to be capitalized
        bit1 - true if no title required
        bit0 - true if changed (used in editor)
        1 byte password flag         0 for no password set
        9 for password set
        if password flag is 9; 9 bytes password information

Note that if this structure is generated by the programmer, the password flag
must be set to 0 to signify no password or the program will try to decrypt the
file when it is loaded.

*******************************************************************************
System Variables

Four system variables that are permanently maintained for the current
notepad can be referenced from outside the notepad editor.

***** NTB_FLGS *****

ADDRESS:    $7FEA
VALUES:    0-$ff but excluding bit3 clear (see below)

This byte contains flags for the editor (see LG$EDIT). The following
bits are currently used:

    bit7 - true if numbered            : may be poked
    bit3 - true if on/clear exits editor    : do not poke
    bit2 - true if prompt to be capitalized    : may be poked
    bit1 - true if no title required    : may be poked
    bit0 - true if changed (used in editor)    : may be poked

The default value for a new notepad is $08 (bit3 set).

Note that if bit3 is cleared then the notepad cannot be exited. This
bit is 0 for editing OPL procedures where the menu includes the item
EXIT.

***** NTB_PSSW *****

ADDRESS:    $7FEB
VALUES:    0 or TRUE.

This byte is 0 if the current notepad in memory has no password or
any non-zero value if a password exists.

It has the default value 0 for a new notepad and is set when a password
is set.

It must not be poked or the editor may attempt to decrypt unencrypted
data or not to decrypt encrypted data etc. with unknown results.

***** NTW_CLIN *****

ADDRESS:    $7FFD
VALUES:    0-$FFFF (see below).

This word contains the current line number in the current notepad.
Line 0 is the line containing the notepad name. This defines which
line the cursor is on.

This variable may be poked to change the line number but should not
be given a value greater than the last line number in the notepad.
The maximum line number is 1 less to the number of zero line-delimiters
in an unencrypted notepad.

***** NTB_CPOS *****

ADDRESS:    $7FFF
VALUES:    0-$FE (see below).

This byte contains the cursor position in the current line in the
current notepad.

This variable may be poked to change the cursor position but should
not be given a value greater than the length of the current line.

*******************************************************************************
System Services

***** NT$ENTR *****

VECTOR NUMBER:    159
INPUT PARAMETERS:    B register - Function number; 0, 1, 2, 3 or
4.


DESCRIPTION

This is the correct way into the notepad from machine code - do not
search the main menu for "Notes" and its address, as its name changes
in multi-lingual versions.

All four functions begin by clearing the diary's paste buffer which
is used in the notepad editor to save the current find string. The
block file type and the cell type are then initialised for Notepad
editing. After the required function has been called, the block file
type and cell type are set up for OPL editing again.

The input parameters, returned values and error codes are specified
for each function separately, or left blank if there are none.

The following functions are available:

Function 0 -    Initialise notepad. This is called on cold booting
the LZ. It inserts the name "Notepad:" into the cell, sets the cursor
to the first editable character, clears the system variable NTB_PSSW
for no password, sets ntb_flgs=8 for no numbering, name not capitalized,
do title line and exit when ON/CLEAR pressed.

Function 1 -    Call the notepad as from the top-level menu option "Notes".

Function 2 -    Search first the current notepad and then all saved
notepads for a given string. Saved notepads are searched in device
order A:, B:, C:. This function is called by the "Search" option on
the "Utils" menu. The find string should be in RTT_FF. If an entry
matches it will be printed on the bottom line of the screen, and the
user can press MODE to edit the notepad at this line, EXE to search
for the next match, or ON/CLEAR to abort the search.

Note that password protected notepads are not searched.

Output Values:    C set: The search went past end of diary.
            C clear, B=0: ON/CLR pressed, search aborted.
            C clear, B=1: MODE pressed, diary entered, then left.

Function 3 -    Edit a named notepad as from a top-level notepad
menu item that has been added by the user. If the name is not the
same as that in the notepad cell, the notepad file is searched for
on the paks in order A:, B:, C: and loaded into the cell. Any error
messages (e.g. File not found, Read pak error) are displayed on detection
and no error codes are returned.

Input Parameters:    UTW_S0 points to the name of the notepad to
be edited.

Function 4 -     Checks whether a notepad file is password protected.

Input Parameters:    UTW_S0 points to the name of the notepad to
be edited

Output Values:    B register 0 if unprotected
            B register TRUE if protected
            A register has other flags for notepad (see discussion above)

ERRORS
    FL$BOPN errors

Note: parameter values 0, 1 and 2 are standard across the interfaces
to the built-in applications ("initialise", "normal entry" and "search").
Values above 2 are application-dependent.

*******************************************************************************
CHAPTER 13    World
*******************************************************************************

The world application gives the current time (ignoring day light time
saving) and dialling code from the base city for 400 cities and 150
countries.

*******************************************************************************
System Services

***** WL$ENTR *****

VECTOR NUMBER:    166
INPUT PARAMETERS:    B register - Function number; 0, 1 or 2.


DESCRIPTION

Function 0 - Initialises the world application. It sets the
base to be London, Paris or Bonn depending on the language byte (btb_lang).  The
initial city is always set to New York Manhattan.

Function 1 - Runs the world application exactly as in the top
level.

Function 2 - Gets the base city and country names into the run
time buffer. Returns with the city name at rtt_bf+100 and the country
name at rtt_bf+120.  Both are byte length strings.  If the current
base is a country (so there is no city) then the country is promoted
to the city field and the country field is blank.

ERRORS
    None.

*******************************************************************************
CHAPTER 14    Alarm
*******************************************************************************

The alarms on the LZ are very similar to those on the standard Organiser,
with information stored in the same 48 byte table. The last byte of
each alarm record now contains additional information on the sound
set for the alarm and the new repeat types.

Bits 0-2 give the repeat setting associated with the alarm, as follows:

    Value        Repeat Setting
    0        Alarm not Set
    1        Hourly
    2        Daily
    3        Workdays
    4        Weekly
    5        Once

The top two bits give the associated tone to go with the alarm:

    Value        Tone
    0        Normal
    1        Siren
    2        Chimes

A system variable AMB_WRKD is provided to indicated which days are
workdays.

*******************************************************************************
System Variables

***** AMB_WRKD *****

ADDRESS:    $20A7
VALUES:    All except the top bit are used.
        The top bit is reserved.

AMB_WRKD is used to determine which days of the week are workdays.
With bit 0 representing Monday, bit 1 Tuesday etc. bits are set for
workdays and cleared otherwise. Thus a value of $4f in AMB_WRKD moves
the weekend to Friday and Saturday.

Setting AMB_WRKD to 0 prevents checking for Workday alarms and removes
the option from alarm setting.

Note - AMB_WRKD should not be set to $80. If it is trying to
set a workday alarm, or having an existing one go off will cause the
machine to lock-up.

*******************************************************************************
System Services

***** AM$ENTR *****

VECTOR NUMBER:    158
INPUT PARAMETERS:    B register - Function number, 0 - 6


DESCRIPTION

Provides an entry point into the ALARM routines.

The available functions are:

Function 0 - Initialise. This clears all alarms and enables
alarm checking by setting AMB_EI.

Function 1 - Calls the ALARM application as from the top level.
Sets the screen to four line mode. Allows alarms to be viewed and
set. On exit restores the screen to previously set mode.

Function 2 - Checks for Diary and ordinary alarms due now and
in the next 34mins and 8 secs. If an alarm is due it will go off.
At most one Diary and two ordinary alarms will go off. The function
then checks for an alarm due in the next 2048 seconds. If an alarm
of any type is due the routine returns with carry set and D contains
the number of seconds before the next alarm. (Note - 2<=D<2048). If
no alarm is due in that time carry is clear on exit.

Output Values:    C clear: No Alarm due in the next 2048s
            C set: An alarm is due in the next 2048s.
            If C is set, D register - number of seconds before alarm

Note: if AMB_EI is clear this function does nothing.

Function 3 - Tests for Diary and ordinary alarm due now. If
one is due it will go off. At most one Diary and one ordinary alarm
will go off.

Note: if AMB_EI is clear this function does nothing.

Function 4 - Checks for unacknowledged diary alarms. This does
the 'Review missed alarms' screen on switch-on. It checks for any
DIARY alarms that have gone off but were not acknowledged by pressing
ON/CLEAR. If there are any it displays a screen showing how many were
missed and will review them. The existing screen is preserved.

Note: if AMB_EI is clear this function does nothing.

Function 5 - Turns alarms off. This function preserves AMB_EI
by copying it to AMB_SEI and then clears it. This disables functions
2,3 & 4 above. Care should be taken with this routine since it cannot
be called again without restoring AMB_EI other wise alarms will be
disabled until AMB_EI is set 'by hand'.

Function 6 - Restores alarm. This copies AMB_SEI back to AMB_EI,
effectively restoring the alarm checking.

ERRORS
    None.

*******************************************************************************
CHAPTER 15    Prog
*******************************************************************************

The PROG application on the LZ is similar to on the standard Organiser.
The editor used in PROG is described in chapter 22, editor.

*******************************************************************************
System Services

***** LG$ENTR *****

VECTOR NUMBER:    175
INPUT PARAMETERS:    B register - Function number; 1 or 2.


DESCRIPTION

Provides an entry point to the PROG application in the top-level menu.
There are 2 functions available:

Function 1 - Call the PROG application as from the top-level
menu.

Function 2 - Search block body files (type in LGB_LANT) that
are on packs for the string in RTT_FF (length in RTB_FL).
Returns the following:

Output Values:    Carry set if not found, or found and then EXE
pressed.
            If carry clear and B=1 the mode key was pressed.
            else if carry clear and B=0 the ON/CLEAR was
            pressed or an error occurred.

EXAMPLE
    None.

ERRORS
    None.

*******************************************************************************
CHAPTER 16    Xfiles
*******************************************************************************

The Xfiles application in the LZ provides access to additional files.
The top-level Find and Save access the MAIN file only which always
has type $90. There can be up to 110 additional files per device (A,B
or C) which will have record types from $91 to $FE. These 'additional'
files have always been accessible from OPL.

Access to the Xfiles application is via XF$ENTR.

Also, a new facility has been introduced to sort a file on pack A:
and this can be called using the system service XF$SORT.

*******************************************************************************
System Services

***** XF$ENTR *****

VECTOR NUMBER:    168
INPUT PARAMETERS:    B register - Function number; 0,1,2,3,4,5.


DESCRIPTION

Provides an entry point to the XFILES application in the top-level
menu.

There are 6 functions available:

Function 0 - Initialises the current XFILES file to be MAIN.

Function 1 - Enters the XFILES application as if from the top-level
menu.

Function 2 - Search files on all devices for the string in RTT_FF
(length in RTB_FL).

Output Values:    Carry set if not found, or found and then EXE
pressed.
            If carry clear and B=1 the mode key was pressed.
            else if carry clear and B=0 the ON/CLEAR was
            pressed or an error occurred.

Function 3 - Find in a file as from a top-level filename that
has been inserted into the menu by the user. The file is search for
on all packs in the order A;, B:, C: and if found made the current
file in XFILES

Input Parameters:    UTW_S0 points to the name of the file to be
opened.

Function 4 - Runs the top-level FIND function

Function 5 - Runs the top-level SAVE function

EXAMPLE
    None.

ERRORS
    None.


***** XF$SORT *****

VECTOR NUMBER:    174
INPUT PARAMETERS:    X register - Points to filename to be sorted.
            D register - Address of routine to call during sorting.
OUTPUT VALUES:    None.


DESCRIPTION

Sorts the file pointed to by the X register. The filename at X is
a leading byte count string of the form "A:NAME" (only files on A
can be sorted).

The D register should point to a subroutine which will be called during
the sort (usually used to print to the screen). When the routine is
called the A register will contain the 'pass' number (1,2,3) and the
X register will contain the record number/number of comparisons, during
the sort. If no routine is required, set D to 0000.

The method used is a Quick Sort algorithm which can be used as a general
sort (see UT$SORT).  The 3 passes are as follows:

    1) Generate the tag list
    2) Sort the tag list
    3) Re-construct the file from the sorted tag list

The total number of bytes in RAM required to sort a file of size S
bytes and containing N records is approximately given by the following
formula:

    Space required = 2 * ( S + N )

If there is insufficient memory for the sort, the file will left alone
and the error ER_AL_NR will be returned.

EXAMPLE
    None.

ERRORS
    ER_AL_NR    - Not enough room for the sort
    ER_FL_NX    - File does not exist
    Any other file errors

*******************************************************************************
CHAPTER 17    Utils
*******************************************************************************

Utils on the LZ provides some useful facilities and these can be accessed
from machine code with the following system services.

*******************************************************************************
System Services

***** XT$ENTR *****

VECTOR NUMBER:    161
INPUT PARAMETERS:    B register - Function number; 0 - 11.

DESCRIPTION

Provides an entry point to the UTILS application in the top-level
menu. There are 12 functions available:

Function 0 - Initialises system password (as no password).

Function 1 - Call the UTILS application as from the top-level menu.

Function 2 - Call the SEARCH option in Utils.

Function 3 - Call the INFO option in Utils.

Function 4 - Call the PASSW option in Utils.

Function 5 - Call the LANG option in Utils.

Function 6 - Check the system password if it is set on (called on warm start).

Function 7 - Actually reset the machine (called from RESET in Utils).

Function 8 - Actually format a RAMPAK (called from FORMAT in Utils).

Input Parameters: A register - the pack to format (1 or 2 for B: or C:).

Function 9 - Call the DIR option in Utils.

Function 10 - Call the COPY option in Utils.

Function 11 - Call the DELETE option in Utils.

EXAMPLE
    None.

ERRORS
    None.


***** XT$BAR *****

VECTOR NUMBER:    162
INPUT PARAMETERS:    A register - % of black on the left.
            B register - % of grey on the right.
OUTPUT VALUES:    Leaves characters for line in RTT_BF:RTT_BF+19
            Sets RTB_BL=20


DESCRIPTION

Sets up the udgs for drawing a bar graph as in the INFO application.
Also leaves characters for drawing the line in the runtime buffer.

EXAMPLE

Draws a bar graph on the second line of the screen with 35% black
and 17% grey.

    LDD    #<35*256+17>
    OS    XT$BAR
    LDX    #RTB_BL
    PSHX
    OS    UT$DISP
    .BYTE    D_HM,D_LF
    .ASCIZ    "%s"
    RTS

ERRORS
      None.

BUGS
      Calling this service with A+B>100 may cause unpredictable results.


***** XT$DIRM *****

VECTOR NUMBER:    156
INPUT PARAMETERS:    X register - Points to the prompt string (lcb).
            B register - Maximum number of characters that can entered.
            A register - File type for directory $81 - $8F or $00 for ALL.
            RTB_BL:RTT_BF - Default filename offered
            UTW_S0  - Line number for prompt 0 or 1 only
                0 for prompt on top line
                1 for prompt on 2nd line
            UTW_S0+1  - flags for the directory display
                0 for no directory, just calls TL$ZZMD
                       1 for directory of files
                2 put sizes of files on right
                4 put in file types on left
                8 put in <*> as entry 1 for COPY etc
                16 insert file type after prompt, (e.g. "Dir of All A:")
                32 Disable EXE key from exiting (e.g. for DIR)
                64 Disable MODE key from switching packs (e.g. for SORT).
OUTPUT VALUES:    A register - file type of file selected    (provided UTW_S0+1 is
                non-zero)
            C set if ON/CLEAR pressed
            else     RTT_BF holds the selected filename.
                TLB_CPAK holds the device selected.

 DESCRIPTION

Produces a directory of files with a prompt like EDIT in PROG etc.
If EXE is used to select a file, the filename will be printed after
the prompt and the lower 2 or 3 lines of the screen will be cleared
when the routine exits.

EXAMPLE
    None.

ERRORS
    None, C set indicates ON/CLEAR exit.

*******************************************************************************
CHAPTER 18    Switching Off
*******************************************************************************

A new facility on the LZ is the ability to switch off for a specified
time before switching back on automatically.  This can be done from
OPL with the "OFF x%" command and from machine code using BT$TOFF.

*******************************************************************************
System Services

***** BT$TOFF *****

VECTOR NUMBER:    129
INPUT PARAMETERS:    D register - No. of seconds to be off for
(2-1800).
OUTPUT VALUES:    None.

DESCRIPTION

Provides a temporary off facility. The machine will switch of for
the number of seconds in the D register before automatically switching
back on and returning from BT$TOFF. The maximum time to be off is
1800 seconds (30 minutes) since the system clock must be updated.
The routine can, of course, be called repeatedly to 'apparently' switch
off for longer times.

EXAMPLE

Switch the machine off for 12 hours.

    LDA    A,#24        ;24 1/2 hours needed
    PSH    A
    LDD    #1800        ;to switch off for 30 seconds
    OS    BT$TOFF
    PUL    A
    DEC    A
    BNE    1$        ;repeat 24 times
    RTS

ERRORS
    None.

BUGS

If the value in the D register is out of range, the routine will not
function correctly. If an ALARM is due before the time to switch back
on, the machine will switch on early to service the alarm.

*******************************************************************************
CHAPTER 19    General Utilities
*******************************************************************************

3 new utilities are provided on the LZ and are described below.

*******************************************************************************
System Services

***** UT$CMPB *****

VECTOR NUMBER:    178
INPUT PARAMETERS:    X register - address of one string.
            UTW_S0  - address of other string.
            A register - length of string at X.
            B register - length of string at UTW_S).
OUTPUT VALUES:    B register -         0 : matched and same length.
                <0 : string at X is first alphabetically.
                >0 : string at UTW_S0 is first alphabetically.
            Z flag     - according to B register.
            N flag     - according to B register.
PRESERVES:    X register.


DESCRIPTION

A case dependant buffer compare. Works in exactly the same way as
UT$ICPB but is case dependant.

EXAMPLE
    None.

ERRORS
    None.


***** UT$WILD *****

VECTOR NUMBER:    148
INPUT PARAMETERS:    A register - length of major string.
            B register - length of minor string.
            X register - address of major string.
            UTW_S0  - address of minor string.
OUTPUT VALUES:    B register - position of match in major string.
            Carry clear if matched, set if no match.


DESCRIPTION

Works in the same way as UT$ISBF except that the wild characters '*'
and '+' apply, i.e. determines whether the minor string at UTW_S0 matches
with the major string at X.

Note the following, where "" is a null string:

    MAJOR STRING    MINOR STRING    MATCH
    "ABC"        ""        FALSE
    ""        ""        TRUE
    ""        "*"        TRUE
    ""        "+"        FALSE

EXAMPLE
    None.

ERRORS
    None.


***** UT$SORT *****

VECTOR NUMBER:    165
INPUT PARAMETERS:    D register - number of items to be sorted
            X register - address of caller supplied routine
OUTPUT VALUES:    None


DESCRIPTION

Provides the core utility for a Quick Sort. The routine assigns space
for a Tag for each of the items to be sorted. The caller's routine
is then called for each item to obtain the Tag. These are then sorted,
again using the routine at X to supply the comparison routine. Once
sorted the Tags are passed in order to the routine at X.

The caller supplied routine is called in three different ways, and
should conform to the following spec:

if b=0
    x - number of record (0-n-1)
    leaves
    x:= tag for that record
if b=1
    x - tag for left hand record
    s0 - tag for right hand record
    should leave condition flags as for 'cmp x,s0'
and when b=2
    x - tag for next record in sorted order

Note - The caller supplied routine MUST NOT use utw_r0,r1,r2
or r3 without preserving the EACH time it is called. Nor should this
routine use the runtime buffer rtb_bl:rtt_bf since this is used in
the sort code at all times.

EXAMPLE

Sorts the qwerty alphabet into order

    LDD    #26
    LDX    #MYROUTINE
    OS    UT$SORT
    BCC    OKRTS
    OS    ER$MESS
OKRTS:     RTS

MYROUTINE:
    TST    B
    BNE    1$
    XGDX            ; returns address of letter
    ADDD    #ORIGINAL
    XGDX
    RTS

1$:    DEC    B
    BNE    2$
    LDA    A,0,X
    LDX    UTW_S0:
    LDA    B,0,x
    CBA            ; does comparison
    RTS

2$:    LDA    A,0,X        ; copies sorted letters in order
    LDX    SRTTAG
    STA    A,0,X
    INX
    STX    SRTTAG
    RTS

SRTTAG:
    .word    SORTED
ORIGINAL:
    .ascii "QWERTYUIOPASDFGHJKLZXCVBNM"
SORTED:
    .ascii "00000000000000000000000000"

ERRORS
    ER_AL_NR - either failed to allocate space for the tags or developed
too many partitions.

*******************************************************************************
CHAPTER 20    List Functions
*******************************************************************************

6 new functions are provided which work on lists of numbers.

*******************************************************************************
System Services

***** FN$SUM *****

VECTOR NUMBER:    137
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.

DESCRIPTION

Returns the sum of the floating-point numbers pointed to by the parameter
on the run-time stack at RTA_SP. The number of floats is passed as
a word on the stack at RTA_SP+2.The result is pushed onto the run-time
stack, leaving the input parameters intact.

EXAMPLE

The follow code calculates the sum of COUNT floats at TABFLOATS and
leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$SUM          ;SUM ON STACK
        BCS     ERROR2
        RTS

ERRORS
    ER_MT_EX    - exponent overflow
    ER_IM_OV    - stack overflow


***** FN$MEAN *****

VECTOR NUMBER:    138
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the arithmetic mean of the floating-point numbers pointed
to by the parameter on the run-time stack at RTA_SP. The number of
floats is passed as a word on the stack at RTA_SP+2.

The result is pushed onto the run-time stack, leaving the input parameters
intact. The follow code calculates the sum of COUNT floats at TABFLOATS
and leaves the result on the stack.

EXAMPLE

The follow code calculates the arithmetic mean of COUNT floats at
TABFLOATS and leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$MEAN         ;MEAN ON STACK
        BCS     ERROR2
        RTS

ERRORS
    ER_MT_EX    - exponent overflow
    ER_IM_OV    - stack overflow


***** FN$VAR *****

VECTOR NUMBER:    139
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the sample variance of the floating-point numbers pointed
to by the parameter on the run-time stack at RTA_SP. The number of
floats is passed as a word on the stack at RTA_SP+2.

The result is pushed onto the run-time stack, leaving the input parameters
intact.

The sample variance differs from the population variance in assuming
that the data set provided constitutes a sample of the data rather
than the complete population.

The sample variance has the formula:
              N
    var(Xi) = (Sigma (Xi-Xm)**2)/(N-1)
              i=1
where Xm is the arithmetic mean.

If the complete data set IS provided, the population variance can
be calculated by multiplying the sample variance by (N-1)/N.

EXAMPLE

The follow code calculates the sample variance of COUNT floats at
TABFLOATS and leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$VAR          ;VARIANCE ON STACK
        BCS     ERROR2
        RTS

ERRORS
        ER_MT_EX    - exponent overflow
        ER_IM_OV    - stack overflow


***** FN$STD *****

VECTOR NUMBER:    140
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the sample standard deviation of the floating-point numbers
pointed to by the parameter on the run-time stack at RTA_SP. The number
of floats is passed as a word on the stack at RTA_SP+2.

The result is pushed onto the run-time stack, leaving the input parameters
intact.

The sample standard deviation differs from the population standard
deviation in assuming that the data set provided constitutes a sample
of the data rather than the complete population.

The sample standard deviation has the formula:
                      N
    std(Xi) = sqrt((Sigma (Xi-Xm)**2)/(N-1)) = sqrt(var(Xi))
                     i=1
where Xm is the arithmetic mean.

If the complete data set IS provided, the population standard deviation
can be calculated by multiplying the sample standard deviation by
sqrt((N-1)/N).

EXAMPLE

The follow code calculates the sample standard deviation of COUNT
floats at TABFLOATS and leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$STD          ;STD ON STACK
        BCS     ERROR2
        RTS

ERRORS
        ER_MT_EX    - exponent overflow
        ER_IM_OV    - stack overflow


***** FN$MIN *****

VECTOR NUMBER:    141
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the minimum of the floating-point numbers pointed to by the
parameter on the run-time stack at RTA_SP. The number of floats is
passed as a word on the stack at RTA_SP+2.

The result is pushed onto the run-time stack, leaving the input parameters
intact.

EXAMPLE

The follow code finds the minimum of the COUNT floats at TABFLOATS
and leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$MIN          ;MINIMUM VALUE ON STACK
        BCS     ERROR1          ;STACK OVERFLOW
        RTS

ERRORS
        ER_IM_OV    - stack overflow


***** FN$MAX *****

VECTOR NUMBER:    142
INPUT PARAMETERS:    Pointer on stack to floating-point numbers.
            Word on stack specifying the number of floats.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the maximum of the floating-point numbers pointed to by the
parameter on the run-time stack at RTA_SP. The number of floats is
passed as a word on the stack at RTA_SP+2.

The result is pushed onto the run-time stack, leaving the input parameters
intact.

EXAMPLE

The follow code finds the maximum of the COUNT floats at TABFLOATS
and leaves the result on the stack.

        LDD     RTA_SP:         ;CURRENT RUNTIME STACK POINTER
        SUBD    #4              ;PREPARE TO PUSH 2 WORDS
        XGDX
        CPX     ALA_FREE        ;ENOUGH MEMORY FREE?
        BCS     ERROR1          ;NO
        STX     RTA_SP:         ;NEW STACK POINTER
        LDD     #TABFLOATS      ;POINT TO TABLE OF FLOATS
        STD     0,X             ;POINTER ON STACK
        LDD     COUNT           ;COUNT OF FLOATS AT TABFLOATS
        STD     2,X             ;COUNT ON STACK
        OS      FN$MAX          ;MAXIMUM ON STACK
        BCS     ERROR1          ;STACK OVERFLOW
        RTS

ERRORS
        ER_IM_OV    - stack overflow

*******************************************************************************
CHAPTER 21    Trig Functions
*******************************************************************************

2 new trig functions are provided described below.

*******************************************************************************
System Services

***** FN$ASIN *****

VECTOR NUMBER:    172
INPUT PARAMETERS:    Floating-point argument on the stack.
OUTPUT VALUES:    Floating-point result on the stack.


DESCRIPTION

Returns the arcsine in radians of the floating-point number on the
run-time stack. The stack pointer (RTA_SP) remains unchanged.

EXAMPLE

The following code returns the arcsine of 0.5 in FN_RESULT.

        LDD     RTA_SP:
        SUBD    #8              ;make room for argument on stack
        STD     RTA_SP:         ;D now has destination for UT$CPYB
        LDX     #8              ;length for copying argument
        STX     UTW_S0:
        LDX     #FN_ARG         ;source address for UT$CPYB
        OS      UT$CPYB         ;copy argument to stack
        OS      FN$ASIN
        BCS     ERROR1
        LDX     RTA_SP:         ;source address for copying result
        LDD     #8
        STD     UTW_S0:         ;length for copying result
        ADDD    RTA_SP:         ;add 8 to stack pointer
        STD     RTA_SP:         ;restore stack pointer
        LDD     #FN_RESULT      ;destination for copy
        OS      UT$CPYB
        RTS

    FN_ARG:
        .BYTE   0,0,0,0,0,$50,-1,0

    FN_RESULT:
        .BLKB   8

    FN_RESULT will now contain the floating-point result 0.523598775598.

ERRORS
    ER_FN_BA    - Bad argument


***** FN$ACOS *****

VECTOR NUMBER:    173
INPUT PARAMETERS:    Floating-point argument on the stack
OUTPUT VALUES:    Floating-point result on the stack.

DESCRIPTION

Returns the arccosine in radians of the floating-point number on the
run-time stack. The stack pointer (RTA_SP) remains unchanged.

EXAMPLE

The following code returns the arccosine of 0.5 in FN_RESULT.

        LDD     RTA_SP:
        SUBD    #8              ;make room for argument on stack
        STD     RTA_SP:         ;D now has destination for UT$CPYB
        LDX     #8              ;length for copying argument
        STX     UTW_S0:
        LDX     #FN_ARG         ;source address for UT$CPYB
        OS      UT$CPYB         ;copy argument to stack
        OS      FN$ACOS
        BCS     ERROR1
        LDX     RTA_SP:         ;source address for copying result
        LDD     #8
        STD     UTW_S0:         ;length for copying result
        ADDD    RTA_SP:         ;add 8 to stack pointer
        STD     RTA_SP:         ;restore stack pointer
        LDD     #FN_RESULT      ;destination for copy
        OS      UT$CPYB
        RTS

    FN_ARG:
        .BYTE   0,0,0,0,0,$50,-1,0

    FN_RESULT:
        .BLKB   8

    FN_RESULT will now contain the floating-point result 1.04719755119.

ERRORS
    ER_FN_BA    - Bad argument

*******************************************************************************
CHAPTER 22    Editor
*******************************************************************************

This section describes the editor used in PROG and NOTES on the LZ
which is also called to produce the CAPTURE editor in Comms-Link.
The system service LG$EDIT provides an entry point to the editor.

TL$ZZMD is also described which uses the 1 line editor and allows
the MODE key to change devices (A:,B:,C:)

*******************************************************************************
System Services

***** LG$EDIT *****

VECTOR NUMBER:    171
INPUT PARAMETERS:    B register - Function number; 0 - 8
            The individual entry points have parameters specified below.
OUTPUT VALUES:    X register - current line
            A register - flags:
                bit7 - true if numbered
                bit2 - true if prompt to be capitalized
                bit1 - true if no title required
                bit0 - true if changed
            B register - position in current line X

DESCRIPTION

General entry point for language editor.

Provides the following in-memory editor functions. Does not handle
files.

Function 0 - Initialise params
Input Parameters:    A register - Block file type             UTW_S0 (msb)
- CELL*2 (e.g. TEXTCELL*2)

Function 1 - New
Input Parameters:    X register - New name

Function 2 - Edit existing cell
Input Parameters:    X register - Current line (0 for 1st line)
            A register - Offset in current line
            UTW_S0 (msb) - flags:
                 bit7 - true if numbered
                 bit2 - true if prompt to be capitalized
                 bit1 - true if no title required
                 bit0 - true if changed

Function 3 - Find

Function 4 - Zap

Function 5 - Top

Function 6 - Bottom

Function 7 - Print

Function 8 - Restore editor status for PROG etc.

Note the following:

  *  Restore (lg$edit (8)) must be called when finished with editor.

  *  UDG 0 must always be defined as the icon for the title line before
     calling EDIT (lg$edit (2)).

  *  The flags returned by LG$EDIT and passed to EDIT (lg$edit (2)) may be
     ignored by passing 0 in the MSB of UTW_S0 before EDIT in which case
     normal editing as in ORGANISER 2 will occur. The cell must exist before
     calling LG$EDIT but may be zeroed. The NEW function inserts a name at
     the start of an existing cell.

To edit an existing cell, the cell MUST have a name terminated by
a colon at the start. The lines are all terminated by a 0.

EXAMPLE

To create a cell for editing and edit it:

    CLR    A        ; 0 initial size of the cell
    CLR    B
    OS    AL$GRAB
    BCS    ERROR        ; Report error
    STX    CELL        ; Save the tag
    XGDX
    SUBD    #ALT_BASE
    STA    B,UTW_S0:    ;cell*2
    CLR    A        ;don't care about lang type of cell
    CLR    B        ;initialise cell
    OS    LG$EDIT
    LDX    #NAME
    LDA    B,#1        ;insert name into zeroed cell
    OS    LG$EDIT
    BCS    ERROR        ;out of memory
    CLR    A        ;initialise editor positions
    CLR    B     STA    B,CURRENT_POS
    STD    CURRENT_LINE
1$:
    LDX    #ICON_PATTERN    ;point to 8 byte icon pattern
    CLR    A        ;8 byte pattern
    CLR    B        ;udg 0
    OS    DP$UDG        ;define udg 0 as the icon for lg$edit (2)
    CLR    UTW_S0        ;not numbered, and dont care if changed
    LDX    CURRENT_LINE    ;X:=0 for line 0
    LDA    A,CURRENT_POS
    LDA    B,#2        ;edit existing cell
    OS    LG$EDIT        ;exit on MODE key, display left intact
    STA    B,CURRENT_POS
    STX    CURRENT_LINE
    BSR    MYMENU    ;C set b=0 means exit, else c set means error
    BCC    1$    ;edit again
    TST    B
    BEQ    OUT
    OS    ER$MESS        ;display error and edit again
    BRA    1$
     OUT:    LDA    B,#8
    OS    LG$EDIT        ;MUST RESTORE editor
    RTS

NAME:    .ASCIC    "CAPTURE"


***** TL$ZZMD *****

VECTOR NUMBER:    155
INPUT PARAMETERS:    X register - Address of prompt string.
            A register - parameter to ED$EDIT.
            B register - maximum input length.
            UTW_S0+1 - line number for prompt (0-3)
OUTPUT VALUES:    B register - key which caused exit.


DESCRIPTION

Works like TL$XXMD except that the screen is not cleared. Prompt is
displayed on line in UTW_S0+1 (0-3).

Returns with C set if ON/CLEAR was used to exit. Key for exit is returned
in B reg.

EXAMPLE
     None.

ERRORS
     None.

*******************************************************************************
CHAPTER 23    Error Printing
*******************************************************************************

Errors are printed in a new format on the LZ if in 4-line mode. In
2-line mode they are printed in the same way as the standard Organiser.  A
new system service ER$PRNT is provided on the LZ to print a text string
in the same format as an error message, unlike ER$MESS which only
prints operating system errors (error code given in the B register).

*******************************************************************************
System Services

***** ER$PRNT *****

VECTOR NUMBER:    169
INPUT PARAMETERS:    X register - Address of leading byte count
string.
OUTPUT VALUES:    None.

DESCRIPTION

Prints the string at X in the same format as an error message.

EXAMPLE

Prints the string "BAD PASSWORD" in the same format as an operating
system error message.

    LDX    #BAD_PASS    ;point to string
    OS    ER$PRNT
    RTS

BAD_PASS:
        .ASCIC  "BAD PASSWORD"

ERRORS
        None.

BUGS
The string to be printed must be <= 20 characters for 4-line mode
and <= 16 characters if it is to be used in 2-line mode.

*******************************************************************************
CHAPTER 24    File Handling
*******************************************************************************

A number of new file system services are provided.

*******************************************************************************
System Services

***** FL$WPAR *****

VECTOR NUMBER:    143
INPUT PARAMETERS:    B register - Length of filename to pars.
            X register - Points to filename.
OUTPUT VALUES:    A register - File type of filename.
            B register - Length of body of name (before '.').
            UTW_S0+1   - 1 if OPO, 2 if OPT, 0 otherwise.


DESCRIPTION

Validates wild card filename at X, with length B. Returns length of
body of filename and the file type for the extension.

    If the extension is ".*", A reg will be 0.
    If there is no extension, A reg will be $ff.

The maximum body length is 8 characters, and file extensions must
be 3 characters or ".*".

For extensions ".OPO" and ".OPT", the file type will be returned as
$83, the same as ".OPL". If this is the case UTW_S0+1 will contain
1 for ".OPO", 2 for ".OPT", or 0 for OPL.

Returns ER_FL_BN error if the filename is illegal.

A null filename is illegal.

EXAMPLE
    None.

ERRORS
    ER_FL_BN    - Bad filename


***** FL$WCAT *****

VECTOR NUMBER:    144
INPUT PARAMETERS:    A register - 1 to start catalogue and 0 to continue.
                        Top bit set if sizes required.
            B register - Device: 0=A:,1=B:,2=C:,3=D:
            X register - Where to put the filename (leading byte count.
            UTW_S0+1   - Length of string at UTW_S1.
                     (if top bit is set, filetype is in UTW_S0)
            UTW_S0(MSB)- File type if top bit of S0+1 is set.
            UTW_S1       - Points to match string.
OUTPUT VALUES:            A register - file type found.
            B register - 1 if OPO, 2 if OPT or 0 otherwise.
            UTW_S0       - contains no of bytes in the block file or
                                     number of records in the ODB file found.
                                     (only if top bit of A was set.)

DESCRIPTION

Provides a wild catalogue of the file names on a device. The routine
must be called first with A register non zero and thereafter with
the A register 0 for each subsequent entry.

Works in the same way as FL$BCAT and FL$CATL except that it returns
only those files which are consistent with the match string pointed
to by UTW_S1. The match string can contain the wild card characters:-

    *  match any number of any characters.
    +  match any 1 character.

It can also contain any of the following file extensions:-

    .ODB        - text (database) files
    .OPL        - OPL procedures (text or object)
    .DIA        - CM/XP diary save files
    .COM        - Comms Link setup files
    .PLN        - Spreadsheet files
    .PAG        - Pager setup files
    .NTS        - Notepad files
    .TY8-TYF     - file types (88-8F)
    .OPT        - OPL procedures (text only)
    .OPO        - OPL procedures (object only)

Wild cards cannot be used in file extensions except * on its own so
that "MAIN.*" will give all types of file called "MAIN".

"*.*" will give all files of all types.

If no file extension is supplied, .* will be assumed, so that "M*"
will give all files of all types starting with "M".

Note that the file extension .OPL will match and file which has Text
or object and .OPO and .OPT work in exactly the same way as .OPL.

If the top bit of UTW_S0+1 is set, it means that there is no extension
in the filespec, but the file type to use is in UTW_S0.

Returns error ER_FL_EF when there are no further directory entries
which match the string supplied.

Note that only X need be passed when A is 0 to continue.

If the top bit of A is set, returns sizes in UTW_S0.

EXAMPLE


The following procedure will provide a catalog of all saved CM/XP
diary files that begin with "D".

    LDA    A,#1        ;A=1 first time
    LDX    #MATCH
    LDA    B,0,X
    STA    B,UTW_S0+1:    ;length of match string
    INX
    STX    UTW_S1:        ;Point to match string
    LDA    B,#MY_DEVICE    ;which device : 0 - 3 for A: to D:
    BRA    FIRST

LOOP:    LDX    #TEMP        ;print byte string in TEMP
    PSHX            ;pass address to UT$DISP
    OS    UT$DISP
    .ASCII    "%s"        ;leading count byte string
    .BYTE    13,10        ; CR LF
    .BYTE    0        ;terminator for format string

    CLR    A        ;A=0 on subsequent calls to FL$WCAT
FIRST:
    LDX    #TEMP        ;filenames placed in TEMP by FL$WCAT
    OS    FL$WCAT
    BCC    LOOP        ;repeat until error returned
    CMP    B,#ER_FL_EF    ;eof err means normal completion
    BEQ    DONE
ERROR:    ...            ;otherwise report error

DONE:    ...

MATCH:    .ASCIC    "D*.DIA"

ERRORS
    ER_PK_NP    - no pak in slot
    ER_PK_DE    - bad or damaged pak in slot
    ER_PK_DV    - selected an invalid pak.
    ER_FL_EF    - No more entries.
    ER_FL_BN    - Bad file name.



***** FL$NCAT *****

VECTOR NUMBER:    157
INPUT PARAMETERS:    A register - 1 to start catalogue and 0 to
continue.
                Top bit set if sizes required
            B register - Device type 0,1,2 etc.
            X register - Target for name.
            UTW_S0+1   - Length of string at UTW_S1.
                (if top bit is set, filetype is in S0)
            UTW_S0(MSB)- File type if top bit of S0+1 is set.
            UTW_S1       - Points to match string.
            UTW_S2       - nth match required
OUTPUT VALUES:            A register - file type found.
            B register - 1 if OPO, 2 if OPT or 0 otherwise.
            UTW_S0       - contains no of bytes in the block file
                or number of records in the ODB file found.
                (only if top bit of A was set)


DESCRIPTION

Same as FL$WCAT but gets the S2'th match.

EXAMPLE
    None.

ERRORS
    ER_FL_BN    - Bad file name.
    ER_PK_NP    - no pak in slot.
    ER_PK_DE    - bad or damaged pak in slot.
    ER_PK_DV    - selected an invalid pak.
    ER_FL_EF    - No more entries.


***** FL$WCPY *****

VECTOR NUMBER:    145
INPUT PARAMETERS:    D register - addr of 'copy-to' string.
            X register - addr of 'copy-from' string.
            UTW_S0  - address of user's routine called for each file copied
                (e.g. to print filenames) - 0000 for no routine.
OUTPUT VALUES:    None.


DESCRIPTION

Wild file copy, works in a similar way to FL$COPY.

Copies files or block files from one device to another.

X points to the 'copy from' string, D points to the 'copy to' string.

The copy-from device must not be the same as the copy-to device. A
file may be copied to a different name on the target device. If a
device only is specified in the copy-to string, the file is copied
with the same name.

Note: When used to copy an OPL procedure to a different name, FL$WCPY
does not actually change the name on the first line of the procedure.
This means if an OPL procedure is copied to a different name and then
listed on a printer, it will be shown with the original name.

The following wild cards are allowed in the 'copy-from' name, but
not in the 'copy-to' name.          *  match any number of any characters.
    +  match any 1 character.      It can also contain any of the following
file extensions:-

    .ODB        - text files
    .OPL        - OPL procedures (text and object)
    .OPT        - OPL procedures (text only)
    .OPO        - OPL procedures (object only)
    .DIA        - CM/XP diary save files
    .COM        - Comms Link setup files
    .PLN        - Spreadsheet files
    .PAG        - Pager setup files
    .NTS        - Notepad files
    .TY8-TYF    - file types (88-8F)

Note that if the 'copy-from' name contains wild characters, the 'copy-to'
name must be the device name only, e.g. "B:".

e.g., the following is ILLEGAL:-

    From    A:*.DIA
    To    B:*.ODB

Note that the "to" name can never have wild chars or file extensions.

UTW_S0 contains the address of the user's routine to be called for
each file copied. When it is called, X reg will point to the filename
and A reg will have its file type.

EXAMPLE

To copy all OPL procedures (text and object) starting with the letter
"X" from A: to B:

    CLR    A
    CLR    B
    STD    UTW_S0:        ;no routine called
    LDX    #COPY_FROM
    LDD    #COPY_TO
    OS    FL$WCPY
    BCS    ERROR
    RTS

COPY_FROM:
    .ASCIC    "A:X*.OPL"
COPY_TO:
    .ASCIC    "B:"

ERRORS
    ER_GN_BL    - battery too low
    ER_PK_BR    - read pack err
    ER_FL_CY    - pak not copyable
    ER_FL_DF    - directory full
    ER_FL_NX    - file not found
    ER_FL_BN    - bad file name
    ER_FL_EF    - end of file
    ER_FL_PF    - pack full
    ER_PK_IV    - unknown pack
    ER_PK_NB    - pack not blank
    ER_PK_CH    - pak changed
    ER_PK_DV    - bad device name
    ER_PK_RO    - read only pack
    ER_PK_DE    - write pack err
    ER_PK_NP    - no pack


***** FL$WDEL *****

VECTOR NUMBER:    146
INPUT PARAMETERS:    X register - Address of filename (leading
byte count).
            UTW_S0        - address of user's routine called for each
                file deleted - 0000 for no routine.
OUTPUT VALUES:    None.


DESCRIPTION

Wild file delete, works in a similar way to FL$DELN and FL$BDEL except
that wild card characters and file extensions are allowed.

The file name at X is a leading count byte string of the form D:NNNNNNNN.XXX
where XXX is a 3 letter file extension or ".*"

EXAMPLE


To delete all OPL procedures beginning with "X" from B:

    LDX    #MATCH_STRING
    OS    FL$WDEL
    BCS    ERROR
    RTS

MATCH_STRING:    .ASCIC    "B:X*.OPL"

ERRORS

    ER_GN_BL    - battery too low
    ER_PK_BR    - read pack err
    ER_FL_NX    - file not found
    ER_FL_BN    - bad file name
    ER_PK_IV    - unknown pack
    ER_PK_NB    - pack not blank
    ER_PK_DV    - bad device name
    ER_PK_RO    - read only pack
    ER_PK_DE    - write pack err
    ER_PK_NP    - no pack


***** FL$WFND *****

VECTOR NUMBER:    147
INPUT PARAMETERS:    D register - Address of search string (lbc)
            X register - Where to put the record found (lbc)
OUTPUT VALUES:    A register - the record type of the record found.


DESCRIPTION

Wild FIND, works exactly like FL$FIND but the wild card characters
*, +, can be used.

Finds a record from the current pak into RAM as a leading count byte
string at X. Leaves the record number at the record found.

Starts from the current position - to start from the very beginning,
FL$RSET should be called with d = 1.

EXAMPLE
    None.

ERRORS
    ER_GN_BL    - battery too low
    ER_PK_BR    - read pack err
    ER_FL_EF    - end of file (no match occurred)
    ER_PK_IV    - unknown pack
    ER_PK_NB    - pack not blank
    ER_PK_DV    - bad device name
    ER_PK_DE    - write pack err
    ER_PK_NP    - no pack


***** FL$FDEL *****

VECTOR NUMBER:    176
INPUT PARAMETERS:    D register - Record to delete from.
            X register - No. of records to delete, or $FFFF
                to delete to end of file.
OUTPUT VALUES:    None.


DESCRIPTION

Fast delete of X records starting from record D, of type FLB_RECT
(the current record type). If X=$FFFF, this deletes to end of file.

EXAMPLE
    None.

ERRORS
    None.


***** FL$GETX *****

VECTOR NUMBER:    152
INPUT PARAMETERS:    A register - file type.
            X register - Where to put the file extension.
            UTW_S0+1 - OPL file type IF A=$83.
OUTPUT VALUES:        B register - length of extension copied into X.


DESCRIPTION

Get file extension for type in A reg into X including the ".". The
number of bytes copied is returned in B.

    If A is in range $81 to $8F ".ODB" to ".TYF" will be copied.
    If A=$83, UTW_S0+1 should contain 0 for OPL, 1 for OPO, 2 for OPT.
    If A=0 ".*" is copied (and B returns 2). If A=$FF nothing happens and
       B returns 0.

EXAMPLE
    None.

ERRORS
    None.

BUGS
    If A reg is ridiculous value, garbage will be copied in X.


***** FL$VALX *****

VECTOR NUMBER:    153
INPUT PARAMETERS:    X register - points to ".ext".
            B register - length of extension 0,2 or 4
OUTPUT VALUES:    A register - file type for extension at x.
            UTW_S0+1   - 1 if OPO, 2 if OPT, 0 otherwise.


DESCRIPTION

Returns A as file type for extension at X (points to ".") length B.
If X points to ".*", returns A=0. If B is passed as 0, returns A=$FF.

EXAMPLE
    None.

ERRORS
    ER_FL_BN    - bad file name

*******************************************************************************
CHAPTER 25    Opl Translator
*******************************************************************************

The translator on the LZ is much the same as on the standard Organiser
(for changes to the existing call, see LN$STRT in chapter 30, extensions
to existing system services). One system service has been added to
force translation in two or four line mode.

*******************************************************************************
System Services

***** LN$XSTT *****

VECTOR NUMBER:    154
INPUT PARAMETERS:    B register    - 0 translating language procedure
                - 1 translating CALC expressions
                - 2 locating errors in CALC
                - 3 locating errors in language procedures
            X register     - offset in QCODE to runtime error
                ignored if B register is 0 or 1
            A register     - 0 translation done as for two line machines
                - 1 translation done as for four line machine
OUTPUT VALUES:    If error occurs:
            X register    - offset in source code of error
            B register    - error code
 DESCRIPTION

Acts as existing translator call LN$STRT except that the A register
determines whether the source is to be translated as on existing machines
or with the extra OPL features in the LZ.

EXAMPLE
    None.

ERRORS
    Numerous.

*******************************************************************************
CHAPTER 26    Keyboard
*******************************************************************************

The keyboard on the LZ has been extended to allow SHIFT-EXE, SHIFT-SPACE
and SHIFT-RIGHT-ARROW.  One new system service has been added, KB$CONK.
These SHIFT-KEY functions can be disabled by setting bit 7 of KBB_SPEC.

*******************************************************************************
Shift Exe

To allow the use of SHIFT-EXE, bit 0 of KBB_SPEC must be set. When
set, SHIFT-EXE will be returned as value 14 (e.g. by KB$TEST).

*******************************************************************************
Shift Space

To allow the use of SHIFT-SPACE, bit 1 of KBB_SPEC must be set. When
set, SHIFT-SPACE will be returned as value 15 (e.g. by KB$TEST).

*******************************************************************************
Shift Right-arrow

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 -A acute-.

*******************************************************************************
System Variables

***** KBB_SPEC *****

ADDRESS:    $2185
VALUES:    Bits 7,1 and 0 are used.
        All other bits are reserved.

KBB_SPEC contains flags to handle the 'special' keys.

    Bit 7    - set to disable all special SHIFT keys.
    Bit 1   - set to allow SHIFT-SPACE.
    Bit 0     - set to allow SHIFT-EXE.

It can be read and written to at any time but should be preserved
around applications.

*******************************************************************************
System Services

***** KB$CONK *****

VECTOR NUMBER:    177
INPUT PARAMETERS:    None.
OUTPUT VALUES:    B register - ascii value of key press.


DESCRIPTION

Exactly the same as KB$GETK but turns the cursor ON before waiting
for a key and OFF afterwards.

EXAMPLE
    None.

ERRORS
    None.

*******************************************************************************
CHAPTER 27    Foreign Languages
********************************************************************************

The LZ operating system is multi-lingual and currently 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 - see the
chapter concerning the keyboard.

The 'language byte' BTB_LANG, has been changed, enabling multi-lingual
devices (such as Comms-Link, Spreadsheet etc) to convert to the language
selected.

*******************************************************************************
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 re-booted whenever a language is selected.

These two functions:    1)    Displaying the language menu
            2)    Booting 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 *****

ADDRESS:    $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
DEFAULT:    0

The above values have been pre-assigned but only 3 are available on
each LZ machine. 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 read at any time but should not be written to directly
(TL$LSET must be used).

BTB_LANG can be read on ALL Organiser models but cannot be changed
unless the machine is multi-lingual.

***** XTB_COLD *****

ADDRESS:    $232E
VALUES:    Bits 7 and 0 only are used.
        All other bits are reserved.
DEFUALT:    0

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 *****

VECTOR NUMBER:    128
INPUT PARAMETERS:    B register - language to be loaded.
OUTPUT VALUES:    None.


DESCRIPTION

Sets language to that specified in the B register.  See BTB_LANG (above)
for values. If the language requested is not available, English is
selected. Sets BTB_LANG to the language 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.

EXAMPLE

    LDA    B,#2        ;select German
    OS    TL$LSET
    BCS    ERROR

ERRORS
    ER_AL_NR    - Not enough room for the new language top-level menu.

*******************************************************************************
CHAPTER 28    Passwords
*******************************************************************************

Two types of password protection are available - the ability to set
a system password, to be asked for whenever the LZ/LZ64 is turned
on, and the ability to set a password on a notepad. A password-protected
notepad is stored in encrypted form.

Outside of Psion, no further details are available on this subject.

*******************************************************************************
CHAPTER 29    LZ64 Ram Usage
*******************************************************************************

The RAM in an LZ64 is arranged in a similar fashion to the
ROM in both LZ and LZ64 - 3 "banks" of 16K are switched between,
as required. The memory map is outlined in the "Technical Programming"
appendix in the LZ/LZ64 manual. On the LZ64, the 16K RAM between
addresses $4000 and $8000 is used in the same way as on the CM/XP/LZ
models, for example to hold the current diary (and on the LZ, the
current notepad), except that "PACK A:" starts in the third RAM bank
and, as it grows, works its way through the second bank and then into
the main bank which the other functions (diary etc) use.

PEEKing and POKEing between addresses $4000 and $8000 on an LZ64 will
only access the bank which is currently selected, and is therefore
not recommended.
*******************************************************************************
CHAPTER 30    Extensions To Existing System Services
*******************************************************************************

Some existing system services have been extended for 4-line operation.
*******************************************************************************
DP$EMIT

Seven additional control chars are available in 4 line
mode only:

    D_3R    20    /* refresh 3rd line    */
    D_4R    21    /* refresh 4th line    */
    D_C3    22    /* clear 3rd line    */
    D_C4    23    /* clear 4th line    */
    D_HD    24    /* print high dotted line */
    D_LD    25    /* print low dotted line */
    D_CE    26    /* clear to end of line    */

Notes: D_CB clears line 2. D_HD and D_LD both use UDG 2.

*******************************************************************************
DP$VIEW

This can view lines 0 - 3 in 4-line mode.

*******************************************************************************
MN$DISP

Menus are aligned in 3 columns when in 4-line mode.
Note that any spaces within menu items are now converted to character 254
to save confusion.

*******************************************************************************
ER$MESS

This prints errors on 4 lines if in 4-line mode.

*******************************************************************************
LN$STRT

This translates OPL in the current mode (2- or 4- line) specified by dpb_mode.

*******************************************************************************
UT$DISP

An additional control code has been added to centre
text - DSP_CN (value 31). When this is used, the next string
to be displayed will be centred on the current line,
with the line cleared on either side.

*******************************************************************************
TL$LSET

The number of languages supported is
not as many as on multi-lingual CM/XP machines.

*******************************************************************************
TM$DAYV

This has been extended to work from 1900 to 2155.

*******************************************************************************
DP$SAVE AND DP$REST

These now use DPT_4SAV, the 4-line save buffer, even in 2-line mode,
instead of the previous DPT_SAVE which no longer exists.

*******************************************************************************
DV$BOOT

This jumps to 2-line mode when running "remove" and "install"
vectors which print (unless 4 line mode has been set).

*******************************************************************************
RM$RUNP

Jumps to 2-line mode if running OPL which was translated on ORG II.

*******************************************************************************
ED$EDIT / ED$EPOS

If bit 1 of A register is set, then the edit will exit if an
UP or DOWN arrow key is pressed.
*******************************************************************************
CHAPTER 31    Additional Record Types
*******************************************************************************

The following block body types have been assigned for the following use:

    RECORD TYPE    APPLICATION

    $81        Filenames
    $82        Old diary block files (XDiary)
    $83        OPL procedures
    $84        Comms-Link setup files
    $85        Spreadsheet files
    $86        Pager setup files
    $87        Notepad files
    $88        Reserved
    $8A        Reserved
    $8B        Reserved
    $8C        Reserved
    $8D        Reserved
    $8E        General use
    $8F        Reserved

*******************************************************************************
CHAPTER 32    Release Notes
*******************************************************************************

What follows are notes for the different releases of LZ/LZ64 machines.
All significant enhancements known bugs are listed.

All the bugs noted are fixed for the following release.

*******************************************************************************
Version 4.2

Released on: 16th March 1989

    1) Memory 'grabbed' by devices (e.g. capture buffer in Comms-Link) is not
    shown in INFO.

    2) If LOW BATTERY is detected during a cold start, garbage ALARMS are set.

    3) SORTING a file which contains other records interspersed within its
     own will cause 'extra' records to be added at the front of the file.

    4) SORT does not order records containing the same character repeated
    different numbers of times correctly, e.g. AA and A.

    5) If there is an error in when saving a DIARY (e.g. PACK FULL) during
     TIDY, the DIARY is still be deleted.

    6) If a match string > 10 characters is passed to any of the WILD CARD
    OPL FUNCTIONS (e.g. DIRW) the machine will crash.

    7) OPL VIEW of a null string will crash the machine.
    Also DISP(0,"string") will crash.

    8) 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.

    9) 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.

    10) "Load..." is displayed without clearing the screen on entry to
    the notepad.

    11) In the DIARY "nn entries shortened" says 10 when there is 100 etc.

    12) In WORLD "The Hague" is shown as "The Hage"

    13) Alarms go off accurate to within 1 minute only. They should be
    exact.

    14) If part of an OPL procedure or NOTEPAD is received with COMMS-LINK
    and the connection is broken, the machine may crash.

    15) A bootable pack created on the DEVELOPER runs ok in 2-line mode
    but if COMMS-LINK is present as well, it runs in 4-line mode.

    16) There is a chance of getting a garbage ALARM going off during RESET.

    17) There are some errors in the GERMAN text.

    18) Calling OPL EDIT with an 80 character prompt,
    e.g. AT 20,4 :PRINT "X": :EDIT A$  does not work correctly.

*******************************************************************************
Version 4.3

Released on: 24th April 1989

    1) 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:
    28/APR/89, 29/SEP/89, 29/DEC/89,30/MAR/90, 29/JUN/90, 28/SEP/90 etc

*******************************************************************************
Version 4.4

Released on: 8th May 1989

Current production version with no known bugs.



*******************************************************************************
Index Of New System Services

AM$ENTR        Entry to ALARM

BT$TOFF        Temporary switch off

CA$ENTR        Entry to calculator

DI$ENTR        Entry to Diary and Month
DP$CPRN        update UDG clock
DP$CSET        Set UDG clock
DP$MSET        Set display mode
DP$PVEW        Partial scroll view
DP$UDG         Define/read UDGs

FL$FDEL        Fast record delete
FL$GETX        Get file extension
FL$NCAT        Matches nth filename
FL$VALX        Get value of a file extension
FL$WCAT        Directory with wild card matching
FL$WCPY        Wild card file copy
FL$WDEL        Wild card file delete
FL$WFND        Wild card FIND
FL$WPAR        Parses a wild card filename
FN$ACOS        Floating point arccosine
FN$ASIN        Floating point arcsine
FN$MAX         Floating point MAXIMUM
FN$MEAN        Floating point MEAN
FN$MIN         Floating point MINIMUM
FN$STD         Floating point STANDARD DEVIATION
FN$SUM         Floating point SUM
FN$VAR         Floating point VARIANCE

KB$CONK        Get a key with cursor ON

LG$EDIT        Entry to main editor
LG$ENTR        Entry to PROG
LN$XSTT        OPL translator in specified mode

MN$1DSP        Display 1 line menu
MN$TITL        Display titled menu
MN$XDSP        Display menu with text

NT$ENTR        Entry to NOTES

TI$ENTR        Entry to TIME
TL$LSET        Selects language
TLZZMD         Edit with prompt, MODE selects pack
TM$DNAM        Returns day name
TM$MNAM        Returns month name
TM$NDYS        Calculates number of days
TM$TSET        Sets the system time
TM$WEEK        Calculates week number

UT$CMPB        Case dependant buffer compare
UT$SORT        General sort routine
UT$WILD        Wild character buffer compare

WL$ENTR        Entry to WORLD

XF$ENTR        Entry to XFILES
XF$SORT        Sorts a file
XT$BAR         Draws a bar graph
XT$DIRM        Prints a directory of files
XT$ENTR        Entry to UTILS