![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
The world server provides information about a city or a country, including stored data and calculated results. The server is designed primarily for the ER5 Time application and for applications dealing with dialling information.
The following topics describe some of the functionality provided by the world server API.
The world database is an alphabetically sorted array of city and country entries, which is constructed from a read-only data file, any imported user data files, and any individually added cities/countries.
The read-only file is the main source for the world database, and is usually stored in ROM. The ROM file can be replaced by a read-only file in RAM C:\System\Localization\Wld_Data.dbz
.
Users can individually add, edit or delete entries to/from the world database arrays, or make multiple changes by importing a data file; note that the array is alphabetically re-ordered whenever cities/countries are added or removed. There are some limitations on what entries can be deleted these are discussed in a later section.
Each city has a unique ID comprised of its city and country name TWldID. To access world information, the session owner must first get the ID for the desired city/country from the world server through its connection to the RWorldServer.
Both city and country name are required in the ID because the same city name can be used in more than one country (e.g. London). When a country is fetched, the ID refers to the capital of that country.
The client can use either an exact string match, or prefix matching on the city and country names, to get the ID for a particular city/country. The first match according to the locale country or whole database is returned. Since the database is sorted alphabetically by city and country name this match is the first in alphabetic order. The various find functions return a null TWldID if there is no match.
The client can also navigate backwards or forwards through sequential TWldIDs. When finding the next or previous city, the client is able to specify whether the city is from the same country or anywhere in the world.
The server can also be used to return the ID of the closest city to a given map co-ordinate. From this, the ID of the next closest city can be fetched.
Once the world ID has been obtained for the desired city or country, the associated data stored in the world database can be obtained TCityData and TCountryData respectively. This information includes dial codes, city latitude and longitude, city map position, GMT offsets, and daylight savings zone.
Not all combinations of cities and countries can be modified or deleted and not any name may be used for a city or country. Country names must be unique, and cities must have a unique name within their country though the same name may be used for cities in different countries.
Cities must be added to a valid country and have a valid DST zone. To add a city, a TCityData is filled with the data and the server is called to add the information. Likewise, the server can add new country information contained in a TCountryData.
To update or delete a city or country, the session must first obtain the correct TWldID. Capital cities, the home city, home country or default country cannot be deleted. If a country is deleted, its cities are added to the null country. Any attempt to delete a location from the read-only file, will return an error.
The server is able to notify its sessions of any change in its state through an asynchronous notify function. This allows the session to be notified of a change to the home city, default country, system time or database files.
The API provides the facility to import extra cities and countries into the database from a data file. Only those cities and countries that obey the restrictions discussed in the modification section, see above, are imported.
Importing data updates the information of existing cities or countries. However importing cannot be used to delete data that is already set. The server can be called to clear all imported entries, change the storage location of the data or to use a different data file.
The world database keeps track of its locale, so that it can calculate the correct order of cities and countries. This allows the database to update itself if the read-only file is upgraded or the locale changes.
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |