; Copyright 1996 Acorn Computers Ltd
;
; Licensed under the Apache License, Version 2.0 (the "License");
; you may not use this file except in compliance with the License.
; You may obtain a copy of the License at
;
; http://www.apache.org/licenses/LICENSE-2.0
;
; Unless required by applicable law or agreed to in writing, software
; distributed under the License is distributed on an "AS IS" BASIS,
; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
; See the License for the specific language governing permissions and
; limitations under the License.
;
; > Internat
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