RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

International module


Introduction

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

  • the keyboard - the mapping of keys to character codes
  • the alphabet - the mapping from character codes to characters
  • the country - both of the above mappings.

This module, in conjunction with the RISC OS kernel, controls the selection of these mappings, but it allows the actual mappings to be implemented in other modules, via the service mechanism. Thus, you could write your own international handlers.

Each country is represented by a name and number. The keyboard shares this list, and is normally on the same setting. However, there are cases for the country and the keyboard to be different. For example, the Greek keyboard would not allow you to type * Commands, because only Greek characters could be entered. In this case, the country could remain Greek, while the keyboard setting is changed temporarily for * Commands.

Each alphabet is also represented by a name and number. A country can only have one alphabet associated with it, but an alphabet can be used by many countries. For example, the Latin1 alphabet contains a general enough set of characters to be used by most Western European countries.

You will find tables of the various character sets, and details of keyboard shortcuts both for selecting keyboard layouts and for entering top-bit-set characters, in Table D: Character sets.

Overview and Technical Details

Names and numbers

Country numbers range from 0 to 99, and alphabet numbers are from 100 to 126. Here are lists of the currently available countries and alphabets.

Countries and keyboards

Here is a list of the currently-defined country and keyboard codes (provided by the international module), and the alphabets they use:

Code Country and Keyboard Alphabet
0 Default Selects the configured country. If the configured country is 'Default', the keyboard ID byte is read from the keyboard
1 UK Latin1
2 Master BFont
3 Compact BFont
4 Italy Latin1
5 Spain Latin1
6 France Latin1
7 Germany Latin1
8 Portugal Latin1
9 Esperanto Latin3
10 Greece Greek
11 Sweden Latin1
12 Finland Latin1
13 (not used)
14 Denmark Latin1
15 Norway Latin1
16 Iceland Latin1
17 Canada1 Latin1
18 Canada2 Latin1
19 Canada Latin1
20 Turkey Latin3
21 Arabic Special - ISO 8859/6
22 Ireland Latin1
23 Hong Kong Not defined
24 Russia Cyrillic
25 Russia2 Cyrillic2
26 Israel Hebrew
27 Mexico Latin1
28 LatinAm Latin1
80 ISO1 Latin1
81 ISO2 Latin2
82 ISO3 Latin3
83 ISO4 Latin4

Countries 20 - 23 and 81 - 83, although allocated, are not supported by this module's * Commands.

The keyboard ID byte read by country 0 ('Default') has changed in meaning between RISC OS 2 and 3; it now represents the keyboards physical layout. Consequently you should no longer use this value.

Alphabets

Here is a list of the alphabet codes currently defined, provided by the international module:

Code Alphabet
100 BFont
101 Latin1
102 Latin2
103 Latin3
104 Latin4
105 Cyrillic
106 Arabic
107 Greek
108 Hebrew
120 Cyrillic2

Alphabets 106, although allocated, is not supported by this module's * Commands.

Alphabet

OS_Byte 71 reads or sets the alphabet by number. *Alphabet can also set the alphabet by name. *Alphabets lists all the available alphabets on the system. Remember that you should normally only need to change the country setting as this will also change the alphabet.

Use OS_ServiceCall &43,1 to convert between alphabet name and number forms and OS_ServiceCall &43,3 to convert from alphabet number to name forms.

OS_ServiceCall &43,5 causes a module which recognises the alphabet number to define the characters in an alphabet in the range specified, by issuing VDU 23 commands itself. The call is issued by the OS when OS_Byte 71 is called to set the alphabet and also by OS_Byte 20 and 25.

Keyboard

OS_Byte 71 can also be used to read or set the keyboard number. *Keyboard can set it as well. Remember that you should normally only need to change the country setting as this will also change the keyboard.

When the keyboard setting is changed, by either of the above ways, an OS_ServiceCall &43,6 will be generated automatically. This is a broadcast to all keyboard handler modules that the keyboard selection has changed.

Country

Setting the country will set values for the alphabet and the keyboard. You should not usually have to override these settings. The country number can be read or set with OS_Byte 70. OS_Byte 240 can also read it. *Country can set the country by name. *Countries will list all the available country names. *Configure Country will set the default country by name and store it in CMOS RAM.

Use OS_ServiceCall &43,0 to convert between country name and number forms and OS_ServiceCall &43,2 to convert from country number to name forms.

To get the default alphabet for a country, OS_ServiceCall &43,4 can be called. Remember that the default keyboard number is the same as the country number.

Service calls

RISC OS provides service calls for the use of any module that adds to the set of international character sets and countries.

Service Calls


Service_International
(Service Call &43)

International service

On entry

R1 = &43 (reason code)
R2 = sub-reason code
R3 - R5 depend on R2

On exit

R1 = 0 to claim, else preserved to pass on
R4, R5 depend on R2 on entry

Use

This call should be supported by any modules which add to the set of international character sets and countries. It is used by the international system module * Command interface, and may be called by applications too. See the chapter entitled International module for details.

R2 contains a sub-reason code which indicates which service is required:

R2 Service required
0 Convert country name to country number
1 Convert alphabet name to alphabet number
2 Convert country number to country name
3 Convert alphabet number to alphabet name
4 Convert country number to alphabet number
5 Define range of characters
6 Informative: New keyboard selected for use by keyboard handlers
Sub-reason codes

The following pages give details of each of these sub-reason codes. Most users will not need to issue these service calls directly, but the OS_Byte calls and * Commands use these. The information is provided mainly for writers of modules which provide additional alphabets etc.


Service_International 0
(Service Call &43)

Convert country name to country number

On entry

R1 = &43 (reason code)
R2 = 0 (sub-reason code)
R3 = pointer to country name terminated by a null

On exit

R1 = 0 if claimed, otherwise preserved
R2, R3 preserved
R4 = country number if recognised, preserved if not recognised

Use

Any module providing additional countries should compare the given country name with each country name provided by the module, ignoring case differences between letters and allowing for abbreviations using '.'. If the given country name matches a known country name, then it should claim the service (by setting R1 to 0), and set R4 to the corresponding country number.

If the given country name is not recognised, all registers should be preserved.


Service_International 1
(Service Call &43)

Convert alphabet name to alphabet number

On entry

R1 = &43 (reason code)
R2 = 1 (sub-reason code)
R3 = pointer to alphabet name terminated by a null

On exit

R1 = 0 if claimed, otherwise preserved
R2, R3 preserved
R4 = alphabet number if recognised, preserved if not recognised

Use

Any module providing additional alphabets should compare the given alphabet name with each alphabet name provided by the module, ignoring case differences between letters and allowing for abbreviations using '.'. If the given alphabet name matches a known alphabet name, then it should claim the service (by setting R1 to 0), and set R4 to the corresponding alphabet number.

If the given alphabet name is not recognised, all registers should be preserved.


Service_International 2
(Service Call &43)

Convert country number to country name

On entry

R1 = &43 (reason code)
R2 = 2 (sub-reason code)
R3 = country number
R4 = pointer to buffer for name
R5 = length of buffer in bytes

On exit

R1 = 0 if claimed, otherwise preserved
R2 - R4 preserved
R5 = number of characters put into buffer if recognised, otherwise preserved

Use

Any module providing additional countries should compare the given country number with each country number provided by the module. If the given country number matches a known country number, then it should claim the service (by setting R1 to 0), put the country name in the buffer, and set R5 to the number of characters put in the buffer.

If the given country number is not recognised, all registers should be preserved.


Service_International 3
(Service Call &43)

Convert alphabet number to alphabet name

On entry

R1 = &43 (reason code)
R2 = 3 (sub-reason code)
R3 = alphabet number
R4 = pointer to buffer for name
R5 = length of buffer in bytes

On exit

R1 = 0 if claimed, otherwise preserved
R2 - R4 preserved
R5 = number of characters put into buffer if recognised, otherwise preserved

Use

Any module providing additional alphabets should compare the given alphabet number with each alphabet number provided by the module. If the given alphabet number matches a known alphabet number, then it should claim the service (by setting R1 to 0), put the alphabet name in the buffer, and set R5 to the number of characters put in the buffer.

If the given alphabet number is not recognised, all registers should be preserved.


Service_International 4
(Service Call &43)

Convert country number to alphabet number

On entry

R1 = &43 (reason code)
R2 = 4 (sub-reason code)
R3 = country number

On exit

R1 = 0 if claimed, otherwise preserved
R2, R3 preserved
R4 = alphabet number if recognised, otherwise preserved

Use

Any module providing additional countries should compare the given country number with each country number provided by the module. If the given country number matches a known country number, then it should claim the service (by setting R1 to 0), and set R4 to the corresponding alphabet number.

If the given country number is not recognised, all registers should be preserved.


Service_International 5
(Service Call &43)

Define a range of characters from a given alphabet number

On entry

R1 = &43 (reason code)
R2 = 5 (sub-reason code)
R3 = alphabet number
R4 = ASCII code of first character in range
R5 = ASCII code of last character in range

On exit

R1 = 0 if claimed, otherwise preserved
R2 - R5 preserved

Use

Any module providing additional alphabets should compare the given alphabet number with each alphabet number provided by the module. If the given alphabet number matches a known alphabet number, then that service should be claimed (by setting R1 to 0) and all the characters should be defined in the range R4 to R5 inclusive, using calls to VDU 23. Any characters not defined in the specified alphabet are missed out: for example, most of the characters &80-&8B in Latin1.

If the given alphabet number is not recognised, all registers should be preserved.


Service_International 6
(Service Call &43)

Notification of a new keyboard selection

On entry

R1 = &43 (reason code)
R2 = 6 (sub-reason code)
R3 = new keyboard number
R4 = alphabet number associated with this keyboard

On exit

R1 preserved (call must not be claimed)
R2 - R4 preserved

Use

This service call is for internal use by keyboard handlers. It is sent automatically after the keyboard selection is changed. You must not claim it.

SWI Calls


OS_Byte 70
(SWI &06)

Read/write country number

On entry

R0 = 70 (&46) (reason code)
R1 = 127 to read or country number to write

On exit

R0 is preserved
R1 = country number read or before being overwritten, or 0 if invalid country number passed
R2 is corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns or sets the country number used by the international module.

Related SWIs

OS_Byte 240

Related vectors

ByteV


OS_Byte 71
(SWI &06)

Read/write alphabet or keyboard

On entry

R0 = 71 (&47) (reason code)
R1 =

0 - 126 for setting the alphabet number
127 for reading the current alphabet number
128 - 254 for setting the keyboard number (R1-128)
255 for reading the current keyboard number

On exit

R0 is preserved
R1 = alphabet or keyboard number read or before being overwritten, or 0 if invalid value passed
R2 is corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns or sets the alphabet or keyboard number used by the international module. Their settings can be read without altering them, or you can set a new value for either. This SWI will return a zero if the value passed to set the new value is not one of the known alphabets or keyboards.

Note that the keyboard setting is offset by 128 when being set; eg to set keyboard 3, you must pass 131 in R1. However, when being read its actual value is returned.

Related SWIs

OS_Byte 70

Related vectors

ByteV


OS_Byte 240
(SWI &06)

Read country number

On entry

R0 = 240 (&F0) (reason code)
R1 = 0
R2 = 255

On exit

R0 is preserved
R1 = country number
R2 = user flag (see OS_Byte 241)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the country number used by the international module.

Related SWIs

OS_Byte 70

Related vectors

ByteV

*Commands


*Alphabet

Selects an alphabet

Syntax

*Alphabet [country_name|alphabet_name]

Parameters

country_name - Valid countries are currently Canada, Canada1, Canada2, Compact, Default, Denmark, Esperanto, Finland, France, Germany, Greece, Iceland, ISO1, Israel, Italy, LatinAm, Master, Mexico, Norway, Portugal, Russia, Russia2, Spain, Sweden, and UK. A list of parameters can be obtained with the *Countries command.

alphabet_name - Valid alphabets are currently BFont, Cyrillic, Cyrillic2, Hebrew, Latin1, Latin2, Latin3, Latin4 and Greek. A list of parameters can be obtained with the *Alphabets command.

Use

*Alphabet selects an alphabet, setting the character set according to the country name or alphabet name.

If the given country is Default, then the keyboard ID byte (read from the keyboard) is used as the country number, providing it is in the range 1 - 31. However, since under RISC OS 3 the keyboard ID is used to represent the physical layout of the keyboard rather than the country for which it is layed out, we recommend you don't use this option. (Standard Archimedes keyboards all have a keyboard ID of 1, which would select the UK alphabet; the A4 internal keyboard and PC external keyboard each have a keyboard ID of 2, which would select the French alphabet.)

With no parameter, this command displays the currently selected alphabet.

Example

*Alphabet Latin3

Related commands

*Alphabets

Related SWIs

OS_Byte 71

Related vectors

None


*Alphabets

Lists all the alphabets currently supported

Syntax

*Alphabets

Parameters

None

Use

*Alphabets lists all the alphabets currently supported by your Acorn computer.

Use the *Alphabet command to change the alphabetical set of characters you are using.

Example

*Alphabets
Alphabets:
BFont   Latin1  Latin2  Latin3  Latin4  Cyrillic
Greek   Hebrew  Cyrillic2

Related commands

*Alphabet

Related SWIs

OS_Byte 71

Related vectors

None


*Configure Country

Sets the configured alphabet and keyboard layout

Syntax

*Configure Country country_name

Parameters

country_name - Valid countries are currently Canada, Canada1, Canada2, Compact, Default, Denmark, Esperanto, Finland, France, Germany, Greece, Iceland, ISO1, Israel, Italy, LatinAm, Master, Mexico, Norway, Portugal, Russia, Russia2, Spain, Sweden, and UK. A list of parameters can be obtained with the *Countries command.

Use

*Configure Country sets the configured alphabet and keyboard layout to the appropriate ones for the given country. For countries other than the UK you will also need to load a relocatable module that defines the keyboard layout. (The IntKey application on the RISC OS 3 Support Disc provides several drivers.)

If the given country is Default, then the keyboard ID byte (read from the keyboard) is used as the country number, providing it is in the range 1 - 31. However, since under RISC OS 3 the keyboard ID is used to represent the physical layout of the keyboard rather than the country for which it is layed out, we recommend you don't use this option. (Standard Archimedes keyboards all have a keyboard ID of 1, which would select the UK alphabet and layout; the A4 internal keyboard and PC external keyboard each have a keyboard ID of 2, which would select the French alphabet and layout.)

Example

*Configure Country Italy

Related commands

*Country, *Countries

Related SWIs

OS_Byte 70, OS_Byte 240

Related vectors

None


*Countries

Lists all the countries currently supported

Syntax

*Countries

Parameters

None

Use

*Countries lists all the countries currently supported by modules in the system.

Example

*Countries
Countries:
Default UK      Master  Compact Italy   Spain   France
Germany Portugal        Esperanto       Greece  Sweden
Norway  Iceland Canada1 Canada2 Canada  Russia  Russia2
Israel  Mexico  LatinAm ISO1

Related commands

*Configure Country, *Country, *Alphabet, *Alphabets, *Keyboard

Related SWIs

OS_Byte 70, OS_Byte 240

Related vectors

None


*Country

Selects the appropriate alphabet and keyboard layout for a given country

Syntax

*Country [country_name]

Parameters

country_name - Valid countries are currently Canada, Canada1, Canada2, Compact, Default, Denmark, Esperanto, Finland, France, Germany, Greece, Iceland, ISO1, Israel, Italy, LatinAm, Master, Mexico, Norway, Portugal, Russia, Russia2, Spain, Sweden, and UK. A list of parameters can be obtained with the *Countries command.

Use

*Country selects the appropriate alphabet and keyboard layout for a given country. For countries other than the UK you will also need to load a relocatable module that defines the keyboard layout. (The IntKey application on the RISC OS 3 Support Disc provides several drivers.) If you prefer, you can use *Alphabet and *Keyboard to set independently the alphabet and keyboard layout, leaving the country setting unchanged.

If the given country is Default, then the keyboard ID byte (read from the keyboard) is used as the country number, providing it is in the range 1 - 31. However, since under RISC OS 3 the keyboard ID is used to represent the physical layout of the keyboard rather than the country for which it is layed out, we recommend you don't use this option. (Standard Archimedes keyboards all have a keyboard ID of 1, which would select the UK alphabet and layout; the A4 internal keyboard and PC external keyboard each have a keyboard ID of 2, which would select the French alphabet and layout.)

With no parameter, this command displays the currently selected country.

Example

*Country Italy

Related commands

*Configure Country, *Countries, *Alphabet, *Alphabets, *Keyboard

Related SWIs

OS_Byte 70, OS_Byte 240

Related vectors

None


*Keyboard

Selects the appropriate keyboard layout for a given country

Syntax

*Keyboard [country_name]

Parameters

country_name - Valid countries are currently Canada, Canada1, Canada2, Compact, Default, Denmark, Esperanto, Finland, France, Germany, Greece, Iceland, ISO1, Israel, Italy, LatinAm, Master, Mexico, Norway, Portugal, Russia, Russia2, Spain, Sweden, and UK. A list of parameters can be obtained with the *Countries command.

Use

*Keyboard selects the appropriate keyboard layout for a given country. For countries other than the UK you will also need to load a relocatable module that defines the keyboard layout. (The IntKey application on the RISC OS 3 Support Disc provides several drivers.)

If the given country is Default, then the keyboard ID byte (read from the keyboard) is used as the country number, providing it is in the range 1 - 31. However, since under RISC OS 3 the keyboard ID is used to represent the physical layout of the keyboard rather than the country for which it is layed out, we recommend you don't use this option. (Standard Archimedes keyboards all have a keyboard ID of 1, which would select the UK layout; the A4 internal keyboard and PC external keyboard each have a keyboard ID of 2, which would select the French layout.)

With no parameter, this command displays the currently selected keyboard layout.

Example

*Keyboard Denmark

Related commands

*Country

Related SWIs

OS_Byte 71

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015