RISCOS.com

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

 

The Territory Manager


Introduction

The territory manager provides SWIs and * Commands for applications to access territory modules. Each territory module provides the services and information necessary for both RISC OS 3 and its applications to be easily adapted for use in different territories (ie regions of the world).

Purpose of the territory manager

There are three main purposes in providing the territory manager:

  1. To enable Acorn to produce a version of RISC OS 3 targeted at a foreign market. This requires not only the ability to translate all system text to a foreign language, but also the ability to support different time zones, different alphabets and different keyboard layouts.
  2. To help you write application software so you can easily adapt it for a foreign market.
  3. To enable you to write application software that can cope with using more than one language at the same time.

RISC OS 3 addresses all of these aspects.

Use of the territory manager

The territory manager provides a wide range of services and information to help you.

Use the territory manager wherever possible. Don't make assumptions about any of the features it supports and can provide information on.

If you do use the territory manager, you will find it much easier to modify your programs for supply to international markets, and have a much wider potential user base.

Overview

The territory manager

The territory manager is a new RISC OS 3 module providing control over the localised aspects of the computer. RISC OS itself only uses one territory for all its functions, but the territory manager can have more than one territory module loaded at any one time, and applications can use these additional territories.

Territory modules

A territory module (such as the UK Territory module present in the RISC OS 3 ROM) is a module providing the territory manager with services and information for a specific territory (such as the UK), amongst which are:

  • a keyboard handler for the territory's keyboard layout
  • the correct alphabet for the territory
  • information on the use of that alphabet, including the direction of writing to use, the properties of each character, and variant forms of each character (such as upper/lower case, control characters, and accented characters)
  • a sort order for strings using the territory's alphabet
  • the characters that are used for numbers, and how those numbers are formatted, both as numeric and monetary quantities
  • the time zones and the formats of time and date used in the territory; together with facilities for reading and setting the local time using these formats
  • information on the calendar used in the territory.

Obviously this is only a summary of what is provided; for full information you should see the section entitled Territory manager SWIs and the Territory module SWIs, especially the latter.

Technical details

Loading and setting the current territory

Each computer running RISC OS has a configured value for the current territory, set using *Configure Territory, and stored in its CMOS RAM. On a reset or a power-on, RISC OS will try to load this territory as follows:

  1. It will load any territory modules in ROM. (Typically there is only one, for the territory into which the computer has been sold.) If one of these is the configured territory, no further action is taken.
  2. Otherwise, it will look on the configured device (ie the configured filesystem and drive) for the module &.!Territory.Territory and load it
  3. If successful, it will then search for the directory ...!Territory.Messages, and load any modules it contains. The directory should exist, even it it contains no modules.

At the end of this process:

  • If the configured territory is in ROM, only those territory modules in ROM will be loaded
  • If the configured territory is not in ROM, both those territory modules in ROM and another territory module (hopefully the configured one) will be loaded.

RISC OS then selects as the current territory either the configured territory, or - if it is not present - a default territory from ROM.

The current territory

The current territory is used by RISC OS for all operating system functions that may change from territory to territory. This includes such things as the language used to display menus, and the default time offset from UTC. As we saw above, the current territory will normally be the configured territory; but if that can't be found, a default ROM territory is used instead.

There can only be one current territory for any one computer. This is because the current territory controls such things as the language used for menus. It would be very confusing to have, for example, some of the menus appear in one language and some in another language. In the UK, even if you are editing a German document, you would normally still want the menus to appear in English.

Once the current territory has been set, you can't change it in mid-session. To change the current territory, you should change the configured territory, and ensure that the new current territory you wish to use is available (either in ROM, or in $.!Territory on the default device). You then need to reboot your computer.

Multiple territories

Whilst RISC OS itself only makes use of the computer's one current territory, the territory manager can have more than one territory module loaded. Applications can then make use of these extra territory modules. For example, you may wish to provide an application that can include text in two different languages in the same document. It is useful for such an application to be able to read the information relating to both languages at the same time.

Initialising territory modules

When the territory manager starts, it issues a service call (Service_TerritoryManagerLoaded) to announce its presence to territory modules. Whenever a territory module receives this service call, it must issue the SWI Territory_Register to add itself to the territory manager's list of active territories. A territory module must also issue this SWI whenever its initialisation entry point is called, thus ensuring that if it is initialised after the territory manager, it still registers itself.

Territory_Register

This SWI also registers with the territory manager the entry points to the routines that the territory module uses to provide its information and services. These entry points are called by issuing SWIs to the territory manager, which specify the territory module that is to be used to service the SWI. The territory manager then calls the appropriate entry point in the specified territory module.

Setting up for the current territory

Once the territory manager has started, and any loaded territory modules have registered themselves, it then sets up the current territory. To do so, it:

  • calls Territory_SelectKeyboardHandler to select the keyboard handler
  • calls Territory_Alphabet to find the alphabet number that should be used in the territory
  • issues Service_International 5 to define that alphabet.

Scope of a territory

A territory need not correspond to a country. Rather, a territory is a region for which a single territory module correctly provides all the services and information. As soon as one or more of the services or information differ, you should provide a different territory (but see below). Sometimes you may need to provide more than one territory for a single country. For example, to properly support the whole of Switzerland you would need a separate territory for each of the languages used.

Supporting minor differences

Sometimes it might appear that a region needs to be split into several territories because of a single minor difference. In such cases you may consider supplying a single generic territory with an extra configuration option.

For example, to support the whole of the USA you might think you would need five territories identical in every respect, except for their use of time zones. Instead, you can provide a single USA territory that uses a command to configure the correct time zone. Because supporting different time zones is so common a requirement, the Territory module supplies the *Configure TimeZone command to do so.

For other such minor differences, you can provide your own configuration commands with your territory. For example, an Irish territory might have a configuration command to choose the currency symbol used ('£' for Northern Ireland, or 'Ir£' for Éire).

Remember that if you wish to store this configuration option in CMOS RAM, you must apply for an allocation from Acorn. See the chapter entitled CMOS RAM bytes.

Territory numbers and names

Territory numbers and names must be allocated by Acorn; see the chapter entitled Territory, country and alphabet numbers and names.

Service Calls


Service_TerritoryManagerLoaded
(Service Call &64)

Tell territory modules to register themselves.

On entry

R1 = &64 (reason code)

On exit

All registers preserved

Use

This call is issued by the territory manager when it has started, announcing its presence to territory modules. Whenever a territory module receives this service call, it must issue the SWI Territory_Register to add itself to the territory manager's list of active territories.


Service_TerritoryStarted
(Service Call &75)

New territory starting

On entry

R1 = &75 (reason code)

On exit

This service call should not be claimed.

All registers preserved

Use

This is issued by the territory manager when a new territory has been selected as the machine territory.

This is used by the ROM modules to re-open their messages files. RAM resident modules do not need to take notice of this service call.

Territory manager SWIs


Territory_Number
(SWI &43040)

Returns the territory number of the current territory

On entry

--

On exit

R0 = current territory's number

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the territory number of the current territory (see the chapter entitled Loading and setting the current territory, and *Configure Territory).

Related SWIs

Territory_NumberToName, Territory_NameToNumber

Related vectors

None


Territory_Register
(SWI &43041)

Adds the given territory to the list of active territories

On entry

R0 = territory number
R1 = pointer to table containing list of entry points for SWIs
R2 = value of R12 on entry to territory

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call adds the given territory to the list of active territories, making it available for application programs. A territory module must issue this call from its initialisation entry point when it is initialised, and whenever it receives the service call Service_TerritoryManagerLoaded.

The table pointed to by R1 should contain 43 entries, each of which is a pointer to code to handle one of the SWIs that - although in the territory manager SWI chunk - are actually handled by a territory module. The first entry corresponds to the SWI &4304A, the second to SWI &4304B, and so on through to the last entry which is for SWI &43074. The entry and exit conditions for the SWI handler are as follows:

On entry
R0 - R9 preserved from original entry to the SWI
R11 SWI handler number (0 - 42: ie offset within table)
R12 value of R2 passed to Territory_Register
R13 pointer to supervisor stack
On exit
R0 - R9 return values for the SWI

For a full description of the SWIs themselves, see the chapter entitled Territory module SWIs.

Some of these SWI numbers (currently from &43062 upwards) are reserved for future expansion, and so you obviously cannot implement them. The code for such SWIs must return an error, not just return directly. The error number must be &43040 (for all territories), and the text should be 'Unknown Territory SWI' (or a translation to your territory's language and alphabet).

Related SWIs

Territory_Deregister

Related vectors

None


Territory_Deregister
(SWI &43042)

Removes the given territory from the list of active territories

On entry

R0 = territory number

On exit

R0 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call removes the given territory from the list of active territories. A territory module must issue this call from its finalisation entry point when it is killed.

Related SWIs

Territory_Register

Related vectors

None


Territory_NumberToName
(SWI &43043)

Returns the name of the given territory

On entry

R0 = territory number
R1 = pointer to buffer to contain name of territory in current territory
R2 = length of buffer

On exit

R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the name of the given territory in the current territory's language and alphabet.

Related SWIs

Territory_NameToNumber

Related vectors

None


Territory_Exists
(SWI &43044)

Checks if the given territory is currently present in the machine

On entry

R0 = territory number

On exit

R0 preserved
Z flag set if territory is currently loaded

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call checks if the given territory is currently present in the machine, and can be used by applications.

Related SWIs

None

Related vectors

None


Territory_AlphabetNumberToName
(SWI &43045)

Returns the name of the given alphabet

On entry

R0 = alphabet number
R1 = pointer to buffer to hold name of alphabet in current territory
R2 = length of buffer

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the name of the given alphabet in the current territory's language and alphabet.

Related SWIs

None

Related vectors

None


Territory_SelectAlphabet
(SWI &43046)

Selects the correct alphabet for the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call selects the correct alphabet for the given territory, and defines the system font appropriately.

Related SWIs

Territory_Alphabet

Related vectors

None


Territory_SetTime
(SWI &43047)

Sets the clock to a given 5 byte UTC time

On entry

R0 = pointer to 5 byte UTC time

On exit

R0 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets the clock to a given 5 byte UTC time.

Related SWIs

None

Related vectors

None


Territory_ReadCurrentTimeZone
(SWI &43048)

Returns information on the current time zone

On entry

--

On exit

R0 = pointer to name of current time zone (null terminated)
R1 = offset from UTC to current time zone, in centiseconds (signed 32-bit)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns information on the current time zone, giving its name in the current territory's language and alphabet, and its offset in centiseconds from UTC time.

Related SWIs

Territory_ReadTimeZones

Related vectors

None


Territory_ConvertTimeToUTCOrdinals
(SWI &43049)

Converts a 5 byte UTC time to UTC time ordinals

On entry

R1 = pointer to 5 byte UTC time
R2 = pointer to word aligned buffer to hold ordinals

On exit

R1, R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time to UTC time ordinals. The word-aligned buffer pointed to by R2 holds the following:

Offset Value
0 centiseconds
4 seconds
8 minutes
12 hours (out of 24)
16 day number in month
20 month number in year
24 year number
28 day of week
32 day of year
Related SWIs

Territory_ConvertTimeToOrdinals

Related vectors

None


Territory_ConvertTextToString
(SWI &73075)

Not yet implemented

On entry

--

On exit

All registers preserved

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call is not yet implemented, and returns immediately to the caller, with all registers preserved.

Related SWIs

None

Related vectors

None

Territory module SWIs

The following SWIs are provided by individual territory modules. The territory manager calls these SWIs using the entry points that a territory module passes by calling Territory_Register when it starts, or when the territory manager restarts. If you are writing your own territory module, you should see the documentation of Territory_Register on Territory_Register.

For all of the following SWIs, on entry R0 is used to specify to the territory manager the number of the territory module which will handle the call. A value of -1 means that the current territory (see the chapter entitled Loading and setting the current territory, and *Configure Territory) will handle the call.


Territory_ReadTimeZones
(SWI &4304A)

Returns information on the time zones for the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to name of standard time zone for given territory
R1 = pointer to name of daylight saving (or summer) time for given territory
R2 = offset from UTC to standard time, in centiseconds (signed 32-bit)
R3 = offset from UTC to daylight saving time, in centiseconds (signed 32-bit)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns information on the time zones for the given territory, giving the names of the territory's standard time zone and daylight saving time, and their offsets from UTC time.

Related SWIs

Territory_ReadCurrentTimeZone

Related vectors

None


Territory_ConvertDateAndTime
(SWI &4304B)

Converts a 5 byte UTC time into a string, giving the date and time

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to buffer for resulting string
R3 = size of buffer
R4 = pointer to null terminated format string

On exit

R0 = pointer to buffer (R2 on entry)
R1 = pointer to terminating 0 in buffer
R2 = number of bytes free in buffer
R3 = pointer to format string (R4 on entry)
R4 = preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time into a string, giving the date and time in a territory specific format given by the supplied format string.

The format string is copied directly into the result buffer, except when a '%' character appears. In this case the next two characters are treated as a special field name which is replaced by a component of the current time.

For details of the format field names see the chapter entitled Format field names.

This call is equivalent to the SWI OS_ConvertDateAndTime. You should use it in preference to that call, which just calls this SWI. The resulting string for both calls is in local time for the given territory, and in the local language and alphabet.

Related SWIs

Territory_ConvertStandardDateAndTime, Territory_ConvertStandardDate, Territory_ConvertStandardTime

Related vectors

None


Territory_ConvertStandardDateAndTime
(SWI &4304C)

Converts a 5 byte UTC time into a string, giving the time and date

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to buffer for resulting string
R3 = size of buffer

On exit

R0 = pointer to buffer (R2 on entry)
R1 = pointer to terminating 0 in buffer
R2 = number of bytes free in buffer
R3 preserved.

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time into a string, giving the date and time in a standard territory specific format.

This call is equivalent to the SWI OS_ConvertStandardDateAndTime. You should use it in preference to that call, which just calls this SWI. The resulting string for both calls is in local time for the given territory, and in the local language and alphabet.

Related SWIs

Territory_ConvertDateAndTime, Territory_ConvertStandardDate, Territory_ConvertStandardTime

Related vectors

None


Territory_ConvertStandardDate
(SWI &4304D)

Converts a 5 byte UTC time into a string, giving the date only

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to buffer for resulting string
R3 = size of buffer

On exit

R0 = pointer to buffer (R2 on entry)
R1 = pointer to terminating 0 in buffer
R2 = number of bytes free in buffer
R3 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time into a string, giving the date only in a standard territory specific format. The resulting string is in local time for the given territory, and in the local language and alphabet.

Related SWIs

Territory_ConvertDateAndTime, Territory_ConvertStandardDateAndTime, Territory_ConvertStandardTime

Related vectors

None


Territory_ConvertStandardTime
(SWI &4304E)

Converts a 5 byte UTC time into a string, giving the time only

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to buffer for resulting string
R3 = size of buffer

On exit

R0 = pointer to buffer (R2 on entry)
R1 = pointer to terminating 0 in buffer
R2 = number of bytes free in buffer
R3 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time into a string, giving the time only in a standard territory specific format. The resulting string is in local time for the given territory, and in the local language and alphabet.

Related SWIs

Territory_ConvertDateAndTime, Territory_ConvertStandardDateAndTime, Territory_ConvertStandardDate

Related vectors

None


Territory_ConvertTimeToOrdinals
(SWI &4304F)

Converts a 5 byte UTC time to local time ordinals for the given territory

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to word aligned buffer to hold ordinals

On exit

R1, R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a 5 byte UTC time to local time ordinals for the given territory. The word-aligned buffer pointed to by R2 holds the following:

Offset Value
0 centiseconds
4 seconds
8 minutes
12 hours (out of 24)
16 day number in month
20 month number in year
24 year number
28 day of week
32 day of year
Related SWIs

Territory_ConvertTimeToOrdinals

Related vectors

None


Territory_ConvertTimeStringToOrdinals
(SWI &43050)

Converts a time string to time ordinals

On entry

R0 = territory number, or -1 to use current territory
R1 = reason code:

1 => format string is %24:%MI:%SE
2 => format string is %W3, %DY-%M3-%CE%YR
3 => format string is %W3, %DY-%M3-%CE%YR.%24:%MI:%SE
R2 = pointer to time string
R3 = pointer to word aligned buffer to contain ordinals

On exit

R1 - R3 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts a time string to time ordinals. The time string is expected to be in the local language and alphabet for the given territory - as obtained from Territory_ConvertDateAndTime - with the appropriate format string. The word-aligned buffer pointed to by R3 holds the following:

Offset Value
0 centiseconds
4 seconds
8 minutes
12 hours (out of 24)
16 day number in month
20 month number in year
24 year number

Values that are not present in the string are set to -1.

Related SWIs

Territory_ConvertDateAndTime

Related vectors

None


Territory_ConvertOrdinalsToTime
(SWI &43051)

Converts local time ordinals for the given territory to a 5 byte UTC time

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to block to hold 5 byte UTC time
R2 = pointer to block containing ordinals

On exit

R1, R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call converts local time ordinals for the given territory to a 5 byte UTC time. The word-aligned buffer pointed to by R2 holds the following:

Offset Value
0 centiseconds
4 seconds
8 minutes
12 hours (out of 24)
16 day number in month
20 month number in year
24 year number
Related SWIs

Territory_ConvertTimeToUTCOrdinals, Territory_ConvertTimeToOrdinals

Related vectors

None


Territory_Alphabet
(SWI &43052)

Returns the alphabet number that should be selected for the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = alphabet number used by the given territory (eg 101 = Latin1)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the alphabet number that will be selected if Territory_SelectAlphabet is issued for the given territory.

Related SWIs

Territory_SelectAlphabet

Related vectors

None


Territory_AlphabetIdentifier
(SWI &43053)

Returns an identifier string for the alphabet that should be used for the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to identifier string for the alphabet used by the given territory

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns an identifier string for the alphabet that will be selected if Territory_SelectAlphabet is issued for the given territory (eg 'Latin1' for the Latin 1 alphabet).

The identifier of each alphabet is guaranteed to be the same no matter which territory returns it, and to consist of ASCII characters only (ie 7 bit characters).

Related SWIs

Territory_AlphabetNumberToName, Territory_SelectAlphabet, Territory_Alphabet

Related vectors

None


Territory_SelectKeyboardHandler
(SWI &43054)

Selects the keyboard handler for the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

--

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call selects the keyboard handler for the given territory.

Related SWIs

None

Related vectors

None


Territory_WriteDirection
(SWI &43055)

Returns the direction of writing used in the given territory

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = bit field giving write direction

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the direction of writing used in the given territory, as a bit field in R0:

Bit Value Meaning
0 0 Writing goes from left to right
1 Writing goes from right to left
1 0 Writing goes from top to bottom
1 Writing goes from bottom to top
2 0 Lines of text are horizontal
1 Lines of text are vertical

Bits 3 - 31 are reserved, and are returned as 0.

Related SWIs

None

Related vectors

None


Territory_CharacterPropertyTable
(SWI &43056)

Returns a pointer to a character property table

On entry

R0 = territory number, or -1 to use current territory
R1 = code for required character property table pointer

On exit

R0 = pointer to character property table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to a character property table, which is a 256 bit table indicating whether or not each character in the given territory's alphabet has a particular property. If a bit is set, the corresponding character has that property. Current property tables are:

Code Meaning when bit set
0 character is a control code
1 character is uppercase
2 character is lowercase
3 character is alphabetic character
4 character is a punctuation character
5 character is a white space character
6 character is a digit
7 character is a hex digit
8 character has an accent
9 character flows in the same direction as the territory's write direction
10 character flows in the reverse direction from the territory's write
direction

A character which doesn't have properties 9 or 10 is a natural character which flows in the same direction as the surrounding text. A character can't have both property 9 and property 10.

The C library uses this SWI to build tables for the isalnum, isalpha, iscntrl, isgraph, islower, isprint, ispunct, isspace and isupper functions/macros. If you're programming in C you can instead use these functions/macros to test a character's properties, provided you have previously called the setlocale function.

Related SWIs

None

Related vectors

None


Territory_LowerCaseTable
(SWI &43057)

Returns a pointer to a lower case table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to lower case table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to a lower case table, which is a 256 byte table giving the lower case version of each character in the given territory's alphabet. Characters that do not have a lower case version (eg numbers, punctuation) appear unchanged in the table.

The C library uses this SWI to build tables for the tolower function/macro. If you're programming in C you can instead use tolower to perform lower case conversion, provided you have previously called the setlocale function.

Related SWIs

None

Related vectors

None


Territory_UpperCaseTable
(SWI &43058)

Returns a pointer to an upper case table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to upper case table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to an upper case table, which is a 256 byte table giving the upper case version of each character in the given territory's alphabet. Characters that do not have a lower case version (eg numbers, punctuation) appear unchanged in the table.

The C library uses this SWI to build tables for the toupper function/macro. If you're programming in C you can instead use toupper to perform upper case conversion, provided you have previously called the setlocale function.

Related SWIs

None

Related vectors

None


Territory_ControlTable
(SWI &43059)

Returns a pointer to a control character table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to control character table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to a control character table, which is a 256 byte table giving the value of each character in the given territory's alphabet if it is typed while the Ctrl key is depressed. Characters that do not have a corresponding control character appear unchanged in the table.

Related SWIs

None

Related vectors

None


Territory_PlainTable
(SWI &4305A)

Returns a pointer to an unaccented character table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to unaccented character table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to an unaccented character table, which is a 256 byte table giving the unaccented version of each character in the given territory's alphabet. Characters that are normally unaccented appear unchanged in the table.

Related SWIs

None

Related vectors

None


Territory_ValueTable
(SWI &4305B)

Returns a pointer to a numeric value table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to numeric value table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to a numeric value table, which is a 256 byte table giving the numeric value of each character in the given territory's alphabet when used as a digit. This includes non-decimal numbers: for example, in English '9' has the numeric value 9, and both 'A' and 'a' have the numeric value 10 (as in the hexadecimal number &9A). Characters that do not have a numeric value have the value 0 in the table.

Related SWIs

None

Related vectors

None


Territory_RepresentationTable
(SWI &4305C)

Returns a pointer to a numeric representation table

On entry

R0 = territory number, or -1 to use current territory

On exit

R0 = pointer to numeric representation table

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns a pointer to a numeric representation table, which is a 16 byte table giving the 16 characters in the given territory's alphabet which should be used to represent the values 0 - 15. This includes non-decimal numbers: for example, in English the value 9 is represented by '9', and the value 10 by 'A' (as in the hexadecimal number &9A).

Related SWIs

None

Related vectors

None


Territory_Collate
(SWI &4305D)

Compares two strings in the given territory's alphabet

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to string1 (null terminated)
R2 = pointer to string2 (null terminated)
R3 = flags:

bit 0: ignore case if set
bit 1: ignore accents if set
bits 2-31 are reserved (must be zero)

On exit

R0
< 0 if string1 < string2
= 0 if string1 = string2
> 0 if string1 > string2
R1 - R3 preserved

N set and V clear if string1 < string2 (LT)
Z set if string1 = string2 (EQ).
C set and Z clear if string1 > string2 (HI)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call compares two strings in the given territory's alphabet. It sets the same flags in the Processor Status Register (part of R15, the program counter) as the ARM's numeric comparison instructions do. You should always use this call to compare strings.

The C library function srtrcoll calls this SWI. If you're programming in C you can instead use srtrcoll to compare two strings, provided you have previously called the setlocale function.

Related SWIs

None

Related vectors

None


Territory_ReadSymbols
(SWI &4305E)

Returns various information telling you how to format numbers

On entry

R0 = territory number, or -1 to use current territory
R1 = reason code (see below)

On exit

R0 = requested value

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns various information telling you how to format numbers, in particular monetary quantities. Current reason codes are:

Code Meaning
0 Return pointer to null terminated decimal point string.
1 Return pointer to null terminated thousands separator.
2 Return pointer to byte list containing the size of each group of digits in formatted non-monetary quantities (least significant first):
255 no further grouping
0 repeat last grouping for rest of number
other size of current group; the next byte contains the size of the next most significant group of digits
3 Return pointer to null terminated international currency symbol.
4 Return pointer to null terminated currency symbol in local alphabet.
5 Return pointer to null terminated decimal point used for monetary quantities.
6 Return pointer to null terminated thousands separator for monetary quantities.
7 Return pointer to byte list containing the size of each group of digits in formatted monetary quantities (least significant first):
255 no further grouping
0 repeat last grouping for rest of number
other size of current group; the next byte contains the size of the next most significant group of digits
8 Return pointer to null terminated positive sign used for monetary quantities.
9 Return pointer to null terminated negative sign used for monetary quantities.
10 Return number of fractional digits to be displayed in a formatted international monetary quantity (ie one using the international currency symbol).
11 Return number of fractional digits to be displayed in a formatted monetary quantity.
12 Return for a non-negative formatted monetary quantity:
1 If the currency symbol precedes the value.
0 If the currency symbol succeeds the value.
13 Return for a non-negative formatted monetary quantity:
1 If the currency symbol is separated by a space from the value.
0 If the currency symbol is not separated by a space from the value.
14 Return for a negative formatted monetary quantity:
1 If the currency symbol precedes the value.
0 If the currency symbol succeeds the value.
15 Return for a negative formatted monetary quantity:
1 If the currency symbol is separated by a space from the value.
0 If the currency symbol is not separated by a space from the value.
16 Return for a non-negative formatted monetary quantity:
0 If there are parentheses around the quantity and currency symbol.
1 If the sign string precedes the quantity and currency symbol.
2 If the sign string succeeds the quantity and currency symbol.
3 If the sign string immediately precedes the currency symbol.
4 If the sign string immediately succeeds the currency symbol.
17 Return for a negative formatted monetary quantity:
0 If there are parentheses around the quantity and currency symbol.
1 If the sign string precedes the quantity and currency symbol.
2 If the sign string succeeds the quantity and currency symbol.
3 If the sign string immediately precedes the currency symbol.
4 If the sign string immediately succeeds the currency symbol.
18 Return pointer to null terminated list separator.

The C library function localeconv calls this SWI. If you're programming in C you can instead use localeconv to return formatting information, provided you have previously called the setlocale function.

Related SWIs

None

Related vectors

None


Territory_ReadCalendarInformation
(SWI &4305F)

Returns various information about the given territory's calendar

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to 5 byte UTC time
R2 = pointer to 12 word buffer

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call takes the 5 byte UTC time passed to it, and returns various information about the given territory's calendar in the buffer pointed to by R2:

Offset Value
0 number of first working day in the week
4 number of last working day in the week
8 number of months in the current year
(current = one in which given time falls)
12 number of days in the current month
16 maximum length of AM/PM string
20 maximum length of WE string
24 maximum length of W3 string
28 maximum length of DY string
32 maximum length of ST string (may be zero)
36 maximum length of MO string
40 maximum length of M3 string
44 maximum length of TZ string
Related SWIs

None

Related vectors

None


Territory_NameToNumber
(SWI &43060)

Returns the number of the given territory

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to territory name in the alphabet of the territory pointed to by R0
(null terminated)

On exit

R0 = territory number for given territory (0 if territory unknown)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call accepts the name of one territory in the language of another territory (probably - but not necessarily - different). It returns the number of the named territory.

Related SWIs

None

Related vectors

None


Territory_TransformString
(SWI &43061)

Transforms a string to allow direct territory independent string comparison

On entry

R0 = territory number, or -1 to use current territory
R1 = pointer to buffer to hold transformed string
R2 = pointer to source string (null terminated)
R3 = length of buffer to hold transformed string

On exit

R0 = length of transformed string (excluding terminating null)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call transforms the string pointed to by R2 and places the resulting string into the buffer pointed to by R1. The transformation is such that if a byte by byte comparison is applied to two transformed strings, then the strings will compare less than, equal to or greater than (as though Territory_Collate had been applied to the original strings).

If you call this SWI with R3 set to 0 on entry, R1 may be a null pointer. On exit R0 will contain the length of the transformed string, without altering the buffer. You may then set up a buffer of the required size (remembering to allow for the terminating null) before again calling this SWI to place the string in the buffer.

If R0 on exit is >= R3 on entry (ie the string was too long to fit in the buffer) the contents of the buffer are undefined, but writing will not have occurred beyond the bounds of the buffer, since this call never writes more than R3 bytes.

If copying takes place between strings that overlap the behaviour is undefined.

The C library function strxfrm calls this SWI. If you're programming in C you can instead use strxfrm to transform strings, provided you have previously called the setlocale function.

This call is not available in RISC OS 3 (version 3.00), and leaves the string unaltered in RISC OS 3 (version 3.10).

Related SWIs

None

Related vectors

None

* Commands


*Configure DST

Sets the configured value for daylight saving time to ON

Syntax

*Configure DST

Parameters

None

Use

*Configure DST sets the configured value for daylight saving time to ON.

The time zone is set when you configure the computer's territory, rather than by this command.

For each territory module that is registered, the territory manager uses the name of that territory's daylight saving time to supply an alternative name for this command. For example, if the UK territory module is registered, the command *Configure BST (short for British Summer Time) has the same effect as *Configure DST. This alternative name is also used by the *Status command (see *Status).

Example

*Configure DST
Related commands

*Configure NoDST, *Configure TimeZone

Related SWIs

None

Related vectors

None


*Configure NoDST

Sets the configured value for daylight saving time to OFF

Syntax

*Configure NoDST

Parameters

None

Use

*Configure NoDST sets the configured value for daylight saving time to OFF.

The time zone is set when you configure the computer's territory, rather than by this command.

For each territory module that is registered, the territory manager uses the name of that territory's standard time to supply an alternative name for this command. For example, if the UK territory module is registered, the command *Configure GMT (short for Greenwich Mean Time) has the same effect as *Configure NoDST. This alternative name is also used by the *Status command (see *Status).

Example

*Configure NoDST

Related commands

*Configure DST, *Configure TimeZone

Related SWIs

None

Related vectors

None


*Configure Territory

Sets the configured default territory for the machine

Syntax

*Configure Territory territory

Parameters

territory - The name or number of the territory to use. A list of parameters can be obtained with the *Territories command.

Use

*Configure Territory sets the configured default territory for the machine. Use this command with caution; if you set a territory that is unavailable your computer will not start, and so you will have to reset your CMOS RAM.

Example

*Configure Territory UK
Related commands

*Territories

Related SWIs

None

Related vectors

None


*Configure TimeZone

Sets the configured local time offset from UTC

Syntax

*Configure TimeZone [+|-]hours[:minutes]

Parameters

hours - offset from UTC in hours

minutes - offset from UTC in minutes

Use

*Configure TimeZone sets the configured local time offset from UTC. You should use this command to configure the local time on your machine rather than changing the system clock as was necessary for RISC OS 2. Using the *Configure TimeZone command will ensure that (since the system clock on all machines will represent UTC) timestamps on files will be valid across machines, networks will work correctly across time zones and electronic mail will be correctly timestamped.

The time offset must be in the range -13:45 to +13:45, and must be an exact multiple of 15 minutes.

Example

*Configure TimeZone 9:30 - Northern Territory, Australia

*Configure TimeZone -5 - Eastern USA

Related commands

*Configure DST, *Configure NoDST

Related SWIs

Territory_ReadTimeZones

Related vectors

None


*Territories

Lists the currently loaded territory modules

Syntax

*Territories
Parameters

None

Use

*Territories lists the currently loaded territory modules.

Example

*Territories
1 UK

Related commands

*Configure Territory

Related SWIs

None

Related vectors

None

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