The International module
========================

Author: Tim Dobson
Name: International
Version: 0.01
Circulation: Acorn
History:
    0.01: 17-Mar-89 to 03-Apr-89: First draft.

This document describes the International module version 1.13, as found in
RISC OS 2.00. It also describes the differences between this version and
version 1.05 (the version in Arthur 1.20).

The International module allows the user to tailor his machine for use in
different countries by setting:-

 a) the mapping of keys to character codes (the *keyboard*), and

 b) the mapping from character codes to characters (the *alphabet*), or

 c) both mappings a) and b) at once (the *country*).

This module, in conjunction with the MOS, controls the selection of these
mappings, but the interface allows the actual mappings to be implemented in
one or more separate relocatable modules, via the service mechanism.

Explanation of terms
--------------------

Each country has a *country name* and an associated *country number*.

Each alphabet has an *alphabet name* and an associated *alphabet number*.

Each country has an associated alphabet, but a given alphabet may be
associated with more than one country.

Each country also has an associated keyboard, but keyboards do not have their
own names or numbers; keyboards are specified by country name or country
number.

Country numbers are in the range 0 to 99, alphabet numbers are in the
range 100 to 126.

Modules can provide new country/alphabet names/numbers by responding to
various sub-reason codes of service call Service_International (&43).

Operating system interface
--------------------------

The operating system maintains the following variables:-

1) The current alphabet number, ie the alphabet number of the currently
selected alphabet.

2) The current keyboard number, ie the country number of the currently
selected keyboard.

3) The current country number, ie the country number of the currently
selected country. NB This may not be relevant if the alphabet and/or keyboard
have been set separately.

These variables are controlled by a number of OS_Byte calls:-

OS_Byte &46 - Read/set country
------------------------------

in:     R1 <> 127 : Select country whose country number is R1.

out:    R1 = old country number, if R1 on entry was valid.
        R1 = 0 => R1 on entry did not correspond to a known country (checked
        for by issuing the service to convert the country number into an
        alphabet number).


in:     R1 = 127 : Read country number.

out:    R1 = current country number.


OS_Byte &47 - Read/set alphabet/keyboard
----------------------------------------

in:     R1 in range 0..126: Select alphabet from alphabet number or country
        number specified by R1.

out:    R1 = old alphabet number, if R1 on entry was valid.
        R1 = 0 => R1 on entry did not correspond to a known country or
        alphabet.


in:     R1 = 127: Read alphabet number.

out:    R1 = current alphabet number.


in:     R1 in range 128..254: Select keyboard from country number specified
        by (R1-128).

out:    R1 = old keyboard number, if R1 on entry was valid.
        R1 = 0 => R1 on entry did not correspond to a known country.


in:     R1 = 255: Read keyboard number.

out:    R1 = current keyboard number.


OS_Byte &F0 - Read country number
---------------------------------

in:     R1 = 0
        R2 = &FF

out:    R1 = current country number

This call is provided for backwards compatibility with international versions
of the Master Compact.


Service calls
-------------

The service call Service_International (R1=&43) is issued at various times by
the operating system and by the International module. The reason for the call
is specified by the contents of R2, as follows:-

R2 = &00: Convert country name to country number

in:     R3 -> null-terminated country name string (may be abbreviated
              with '.')

out:    All registers preserved if country not recognised, otherwise:-
        R1 = 0 (call claimed)
        R4 = country number

R2 = &01: Convert alphabet name to alphabet number

in:     R3 -> null-terminated alphabet name string (may be abbreviated
              with '.')

out:    All registers preserved if alphabet not recognised, otherwise:-
        R1 = 0 (call claimed)
        R4 = alphabet number

R2 = &02: Convert country number to country name

in:     R3 = country number
        R4 -> buffer for name
        R5 = buffer length

out:    All registers preserved if country number not recognised, otherwise:-
        R1 = 0 (call claimed)
        Buffer holds country name (no terminator) truncated to buffer length
        R5 = number of characters put into buffer

R2 = &03: Convert alphabet number to alphabet name

in:     R3 = alphabet number
        R4 -> buffer for name
        R5 = buffer length

out:    All registers preserved if alphabet number not recognised, otherwise:-
        R1 = 0 (call claimed)
        Buffer holds alphabet name (no terminator) truncated to buffer length
        R5 = number of characters put into buffer


R2 = &04: Convert country number to alphabet number

in:     R3 = country number

out:    All registers preserved if country number not recognised, otherwise:-
        R1 = 0 (call claimed)
        R4 = alphabet number


R2 = &05: Define a range of characters from a given alphabet

in:     R3 = alphabet number
        R4 = ASCII code of first character in range
        R5 = ASCII code of last character in range

out:    All registers preserved if alphabet number not recognised, otherwise:-
        R1 = 0 (call claimed)

If the alphabet number is recognised by the module, it should define all
characters in the range R4 to R5 inclusive with the appropriate character
shapes (using VDU 23,code,...). Any characters which do not have defined
shapes in the specified alphabet (eg codes &80-&9F in Latin1) should be left
unchanged.

R2 = &06: Notification that the keyboard number has changed.

in:     R3 = new keyboard number
        R4 = alphabet number associated with the keyboard number (not
             necessarily the same as the current alphabet number)

out:    All registers preserved (call should never be claimed).

This call is issued so that modules providing keyboard handlers.


OS_CLI commands provided
------------------------

    *Alphabet [<country name> | <alphabet name>]

*Alphabet sets an alphabet from a country or alphabet name.
*Alphabet with no parameter displays the currently selected alphabet.


    *Country [<country name>]

*Country sets the appropriate alphabet and keyboard driver for a particular
country.
*Country with no parameter displays the currently selected country.


    *Keyboard [<country name>]

*Keyboard sets the keyboard driver for a particular country.
*Keyboard with no parameter displays the currently selected keyboard.


    *Alphabets

*Alphabets lists the names of the available alphabets.


    *Countries

*Countries lists the names of known countries

