This section describes the most relevant use cases of the IlEnvironment class. The handling of ICU resource bundles is explained in Resources.

At application start-up, to activate the localization create an instance of IlEnvironment by calling the IlEnvironment::Get function. Then the application can set its preferred locale and time zone, register specific options and load resource bundles to use localized messages.

For example, when the first connection to the database is initiated, Rogue Wave Views DB Link uses IlEnvironment::Exists to check if the instance already exists and the bundle "ilddb" is already loaded. If not, Rogue Wave Views DB Link tries to load the resource bundle from the directory $ILDHOME/data, where ILDHOME is the installation directory of Rogue Wave Views DB Link.

When the environment instance is created, the default system locale is assigned to it and the time zone is set to GMT.

These are retrieved using the functions getLocale and getTimeZone. Note that both return ICU specific objects.

The locale can be changed using the function setLocale whose arguments specify the characteristic of the required locale to use. At a minimum the first argument must be non null and designates the language to use. The other optional arguments are the country, an indicator of a variant of the language, and a string of comma separated pairs in the format "key=value".

Localized message texts are stored in files using the ICU binary format (these files use the extension ".res").

The IlEnvironment class provides functions to retrieve the texts in various character sets:

These functions enable the search of the message text in specific top level bundles as they accept two arguments. The first argument is the message key, and the second optional argument indicates in which bundle to search.

Application specific options are stored into a list of pairs (key, value). Options may be added, changed, or removed from the list. Both key and value are received and returned as strings by the API functions.

An option is added to the list using the function setOption which takes two arguments: the key and the value.

An option value is changed using the function setOptionValue which, also, takes two arguments: the key and the new value.

The value of an option is retrieved using the function getOptionValue which sole argument is the key.

The function getOption behaves somewhat differently from getOptionValue. It takes two arguments: the option key and a default value. While getOptionValue may return null if the option is not found in the list, getOption will instead return the default value.

An additional function getEnvOrOption is provided to retrieve a value either from the system environment or the internal options list. This function takes three arguments: the name of an environment variable, the option key, and a default value. The function first looks into the system environment for a variable with the given name. If such a variable is found, its value is returned. Otherwise, it looks into the internal options list using the key and returns its value if found. Otherwise, it returns the default value.

The function getResource, taking two arguments: a resource name and a default value, returns the result from calling the resource call-back function or the default value if no value was returned or no call-back function was set.

The function getEnvOrResource takes three arguments whose semantic is close to the one of the getEnvOrOption function arguments.

The function first searches the system environment for a variable with the given name and returns its value if found. Otherwise it calls the function getResource.