This class contains the description of the environment the application is running in. More...

#include <ildblink/ilenv.h>

Public Member Functions
virtual	~IlEnvironment ()
	This virtual destructor must be invoked when the application terminates. More...

IlUChar *	getBinaryResource (int level, const char bundleNames[], IlInt &len, const char key=0)
	Retrieve a binary vector from the current resource bundle. More...

UnicodeString	getCharResource (int level, const char bundleNames[], const char key=0)
	Retrieve a text. More...

DateFormat *	getDateTimeFormatter ()
	Get the current date and time formatter. More...

const char *	getEnvOrOption (const char name, const char resName=0, const char *def=0) const
	Retrieve the value of an option. More...

const char *	getEnvOrResource (const char name, const char resName=0, const char *def=0) const
	Retrieve the value of a resource. More...

IlInt	getIntResource (int level, const char bundleNames[], const char key=0)
	Retrieve an integer from the current resource bundle. More...

IlInt	getIntVectNthResource (int level, const char bundleNames[], IlInt nth, const char key=0)
	Retrieve a value in a vector of integers from the current resource bundle. More...

IlInt *	getIntVectResource (int level, const char bundleNames[], IlInt &len, const char key=0)
	Retrieve a vector of integers from the current resource bundle. More...

Locale	getLocale () const
	Get the current locale. More...

char *	getMessage (const char key, const char bName=0)
	Retrieve a message text. More...

UnicodeString	getMessageUString (const char key, const char bName=0)
	Retrieve a message text. More...

char *	getMessageUTF8 (const char key, const char bName=0)
	Retrieve a message text. More...

NumberFormat *	getNumberFormatter ()
	Get the current number formatter. More...

const char *	getOption (const char name, const char def=0) const
	Retrieve the value of an option. More...

const char *	getOptionValue (char *key) const
	Retrieve the value of an option. More...

const char *	getResource (const char name, const char def=0) const
	Retrieve the value of a resource using the resource callback function. More...

ResourceBundle *	getResources (const char *bName=0) const
	Get the current top level resource bundle. More...

TimeZone *	getTimeZone () const
	Get the current time zone. More...

UnicodeString &	getTimeZoneId (UnicodeString &ustr) const
	Get the current time zone identifier. More...

IlBoolean	loadResources (const char *bName=0)
	Load a resource bundle for the current locale. More...

IlChangeLocaleFunc	setChangeLocaleCallback (IlChangeLocaleFunc f, IlAny cbkData=0)
	Set a callback function to be called whenever the application locale is changed. More...

IlBoolean	setDateTimeFormatter (DateFormat *fmt)
	Set the current date and time formatter. More...

IlGetResFunc	setGetResourceCallback (IlGetResFunc f, IlAny cbkData=0)
	Set a callback function to be called whenever the `getResource` member funtion is called. More...

virtual IlBoolean	setLocale (const char language, const char country=0, const char variant=0, const char keysAndVals=0)
	Set the current locale to the one defined by the given arguments. More...

IlBoolean	setNumberFormatter (NumberFormat *fmt)
	Set the current number formatter. More...

void	setOption (char key, char value)
	Set the value of an option under some key. More...

IlBoolean	setOptionValue (char key, char value)
	Modify the value of an option under some key. More...

virtual IlBoolean	setTimeZone (UnicodeString tz)
	Set the current time zone to the one defined by the given argument. More...

Static Public Member Functions
static IlBoolean	Exists ()
	This static function tells if an environment instance was created or not. More...

static IlEnvironment *	Get ()
	This static function is the only way to gain access to the unique environment object an application has. More...

Detailed Description

This class contains the description of the environment the application is running in.

Library: dbkernel

This class is a container to store all data items pertaining to runtime environment like locale, timezone, resources, date and time formatter, number formatter, and specific options.

Locales, timezones, and resources are managed using ICU exclusively. Options are freeform, provided keys are strings and one knows what type is the value. Resoure bundle elements can be those defined by ICU (International Components for Unicode). The formal structure of resource bundles is precisely the one from ICU: http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt

Date and time formatter and number formatter are not allocated initially: they will be created, according to the current locale and timezone, the first time they are accessed.

Constructor & Destructor Documentation

virtual IlEnvironment::~IlEnvironment ( )

virtual

This virtual destructor must be invoked when the application terminates.

The destructor cleans up all its internal structures including the loaded resource bundles. Option keys and values will not be deleted since they were provided by the application and may be used in other places.

Note: The destructor can be called at any time. Such a call will completely remove the existing instance but a brand new one will be created by a call to IlEnvironment::Get.

Member Function Documentation

static IlBoolean IlEnvironment::Exists ( )

static

This static function tells if an environment instance was created or not.

Returns: IlTrue if an environment object has been created, IlFalse otehrwise.

No environment instance is created by default. It is the application initiative to get one using the IlEnvironment::Get function and then to alter its default settings like locale and time zone; and also to ensure some resources (in the ICU sense) are loaded.

See Also: setLocale, setTimeZone, loadResources

static IlEnvironment* IlEnvironment::Get ( )

static

This static function is the only way to gain access to the unique environment object an application has.

Returns: The unique environment object.

If no environment object exists at the time this function is called, one will be created as follows:

The locale is set to the system current one.
The time zone is GMT.
No resources are loaded.
No options are set.
No callback function will be preset for getting resources or be warned of locale changes. Consequently no data will be stored for the callback functions.
No resource bundle access path set.

Note: It is the application responsibility to check the environment objet is properly formed: use the isBad() function. If this call returns IlTrue, then the creation of the default locale object or the initialization of the ICU library failed.

See Also: isBad().

IlUChar* IlEnvironment::getBinaryResource	(	int	level,
		const char *	bundleNames[],
		IlInt &	len,
		const char *	key = `0`
	)

Retrieve a binary vector from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
len	An output argument that will, upon successful completion, contains the number of entries in the returned vector.
key	Optional, a key in the last bundle accessed.

Returns: A binary vector that makes up the value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is 0, and the len argument is set to 0.

Note: It is the application responsibility to delete the array.

UnicodeString IlEnvironment::getCharResource	(	int	level,
		const char *	bundleNames[],
		const char *	key = `0`
	)

Retrieve a text.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
key	Optional, a key in the last bundle accessed.

Returns: A UnicodeString object containing the resource text.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (array or table).

In case of error, the returned object state is undefined.

DateFormat* IlEnvironment::getDateTimeFormatter ( )

Get the current date and time formatter.

Returns: A pointer to the internal date and time formatter.

If no formatter was previously set, one will be automatically created. If the creation failed, a null pointer is returned.

const char* IlEnvironment::getEnvOrOption	(	const char *	name,
		const char *	resName = `0`,
		const char *	def = `0`
	)		const

Retrieve the value of an option.

Parameters

name	The name of an environment variable.
resName	Optional, the option name if internally defined.
def	Optional, the default value to return in case no option with this name exists.

Returns: The option or environment value, or the given default value.

The function will first look into the system environment if a variable named name exists, then it will return its value. Else, it will search the application array of options using resName, if given, as key. Finally, if both approaches failed, it will return the given default def.

const char* IlEnvironment::getEnvOrResource	(	const char *	name,
		const char *	resName = `0`,
		const char *	def = `0`
	)		const

Retrieve the value of a resource.

Parameters

name	The name of an environment variable.
resName	The name used to store the value of the resource.
def	Optional, the default value to return in case no resource of this name exists.

Returns: The resource value or the given default value.

The function will first look into the system environement if a variable named name exists. If so it will return its value. Else, it will call the resource callback function using resName, if given, as key. Finally, if both approaches failed, it will return the given default def.

See Also: getResource

IlInt IlEnvironment::getIntResource	(	int	level,
		const char *	bundleNames[],
		const char *	key = `0`
	)

Retrieve an integer from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
key	Optional, a key in the last bundle accessed.

Returns: The integer value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is INT_MIN.

IlInt IlEnvironment::getIntVectNthResource	(	int	level,
		const char *	bundleNames[],
		IlInt	nth,
		const char *	key = `0`
	)

Retrieve a value in a vector of integers from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will dive into one after the other.
nth	The order of the value to retrieve in the vector,
key	Optional, a key in the last bundle accessed.

Returns: The integer at the nth position in the vector.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is the smallest possible integer (INT_MIN).

IlInt* IlEnvironment::getIntVectResource	(	int	level,
		const char *	bundleNames[],
		IlInt &	len,
		const char *	key = `0`
	)

Retrieve a vector of integers from the current resource bundle.

Parameters

level	The number of actual entries in the second argument.
bundleNames	An array of bundle names, the function will go into one after the other.
len	This output argument will, upon successful completion, contains the number of entries in the returned vector.
key	Optional, a key in the last bundle accessed.

Returns: A vector of integers that makes up the value of the resource.

The first bundle name should identify a top level bundle. This function will traverse the bundles one after the other, retrieving them by name. It is assumed the names in the array are in the proper order. The last argument key should be given when the last bundle in the descent is of a composed type (integer vector, array or table).

In case of error, the returned value is 0, and the len argument is set to 0.

Note: It is the application responsibility to delete the array.

Locale IlEnvironment::getLocale ( ) const

Get the current locale.

Returns: a Locale object.

char* IlEnvironment::getMessage	(	const char *	key,
		const char *	bName = `0`
	)

Retrieve a message text.

Parameters

key	the message key. It must be a string whose characters all belong to the invariant section of Unicode (the ASCII characters).
bName	the bundle name in which to look for the message text.

Returns: A string containing the message text.

The second argument bName may be null but not the empty string. If it is null and a bundle at least was loaded, the search will happen into the last loaded bundle.

This function is based on the following assumptions:

at least one bundle has been loaded beforehand.
any bundle in any locale has a first level sub-bundle whose name is 'messages'.
this sub-bundle is composed of items which all have a key and a string contents, that is this sub-bundle is of type 'table'.

In case of error, the returned object state is undefined.

Note: It is the application responsibility to check the state of the environment object using the isBad function. It is also the application responsibility to destroy the returned string once done with it.

See Also: getResources

UnicodeString IlEnvironment::getMessageUString	(	const char *	key,
		const char *	bName = `0`
	)

Retrieve a message text.

Parameters

key	The message key. It must be a string whose characters all belong to the invariant section of Unicode (the ASCII characters).
bName	The bundle name in which to look for the message text.

Returns: A UnicodeString object containing the message text.

This function is based on the same assumptions as the function getMessage.

In case of error, the returned object state is undefined.

char* IlEnvironment::getMessageUTF8	(	const char *	key,
		const char *	bName = `0`
	)

Retrieve a message text.

Parameters

key	The message key. It must be a string whose characters all belong to the invariant section of Unicode (the ASCII characters).
bName	The bundle name in which to look for the message text.

Returns: A pointer to a UTF8 encoded string containing the message text.

This function is based on the same assumptions as the function getMessage. In case of error, the returned object is null.

Note: It is the application responsibility to destroy the returned string once done with it.

NumberFormat* IlEnvironment::getNumberFormatter ( )

Get the current number formatter.

Returns: A pointer to the internal number formatter.

If no formatter was previously set, one will be automatically created. If the creation failed, a null pointer is returned. The maximum number of fraction digits of the created formatter is set to IL_MAX_FRAC_DIGITS (12).

const char* IlEnvironment::getOption	(	const char *	name,
		const char *	def = `0`
	)		const

Retrieve the value of an option.

Parameters

name	The name used to store the value of the option.
def	The default value to return in case no option of this name exists.

Returns: The option value or the given default value.

All option values must be under string form. If one needs to be an integer or real number, it is the application responsibility to proceed to the transformation.

const char* IlEnvironment::getOptionValue ( char * key ) const

Retrieve the value of an option.

Parameters

key	The key used to store the value of the option.

Returns: The option value.

All option values must be under string form. If one needs to be an integer or real number, it is the application responsibility to proceed to the transformation.

const char* IlEnvironment::getResource	(	const char *	name,
		const char *	def = `0`
	)		const

Retrieve the value of a resource using the resource callback function.

Parameters

name	The name of a resource.
def	The default value to return in case no resource of this name exists.

Returns: The resource value or the given default value.

If no resource callback function was set, it will always return the default value def.

See Also: setGetResourceCallback

ResourceBundle* IlEnvironment::getResources ( const char * bName = 0 ) const

Get the current top level resource bundle.

Parameters

bName Optional, the name of a resource bundle

Returns: A ResourceBundle object.

This function retrieves a top level resource bundle using its name. It will not search into the loaded bundles. If no name is given, by default, the first top level bundle found is returned. If there are no top level bundle of the given name or no bundle at all loaded, it will return null.

TimeZone* IlEnvironment::getTimeZone ( ) const

Get the current time zone.

Returns: A const pointer to the internal time zone object.

UnicodeString& IlEnvironment::getTimeZoneId ( UnicodeString & ustr ) const

Get the current time zone identifier.

Parameters

ustr	A valid UnicodeString object reference.

Returns: A UnicodeString.

The returned value and the argument are actually the same.

IlBoolean IlEnvironment::loadResources ( const char * bName = 0 )

Load a resource bundle for the current locale.

Parameters

bName The directory where the file for this resource bundle can be found.

Returns: IlTrue if the operation succeeded.

If the bName argument is null, the contents of the data directories array will be used. If the argument is non null, the internal data directories path are searched for a sub-directory with name bName. If such a directory is found, an attempt at loading the resource bundle will be made.

In case of success the bundle can be retrieved using getResources. The files to load must be in ICU compiled format. Thus the loader will look for files with extension '.res'.

Note: The name is used to register the bundle but it is not copied.

IlChangeLocaleFunc IlEnvironment::setChangeLocaleCallback	(	IlChangeLocaleFunc	f,
		IlAny	cbkData = `0`
	)

Set a callback function to be called whenever the application locale is changed.

Parameters

f	The callback function implementing the specific mechanism the application will use.
cbkData	Optionally, some application specific data that will be passed as first argument to the callback function.

Returns: The previous callback function or null.

See Also: IlChangeLocale, setLocale.

IlBoolean IlEnvironment::setDateTimeFormatter ( DateFormat * fmt )

Set the current date and time formatter.

Parameters

fmt	A valid date and time formatter.

Returns: IlFalse if the argument is null.

The fmt argument should have been created using the ICU API DateFormat::createDateTimeInstance(). If the fmt argument is null, the previously set formatter is left unaltered; otherwise the previously set formatter, if any, will be deleted.

IlGetResFunc IlEnvironment::setGetResourceCallback	(	IlGetResFunc	f,
		IlAny	cbkData = `0`
	)

Set a callback function to be called whenever the getResource member funtion is called.

Parameters

f	The callback function implementing the specific mechanism the application will use.
cbkData	Optionally, some application specific data that will be passed as first argument to the callback function.

Returns: The previous callback function or null.

This function cannot fail. So it is possible to remove the callback function and data by calling this function with both arguments set to null.

See Also: IlGetResFunc, getResource.

virtual IlBoolean IlEnvironment::setLocale	(	const char *	language,
		const char *	country = `0`,
		const char *	variant = `0`,
		const char *	keysAndVals = `0`
	)

virtual

Set the current locale to the one defined by the given arguments.

Parameters

language	The new locale language.
country	The optional country for the language.
variant	The optional variant applicable for the language and country combination.
keysAndVals	Optional additional settings for the new locale.

Returns: IlTrue if the locale change went well.

The language value must be one defined by the ISO standard 639-2. The country value must be one defined by the ISO standard 3166.

IlBoolean IlEnvironment::setNumberFormatter ( NumberFormat * fmt )

Set the current number formatter.

Parameters

fmt	A valid number format.

Returns: IlFalse if the argument is null.

The fmt argument should have been created using the ICU API NumberFormat::createInstance(). If the fmt argument is null, the previously set formatter is left unaltered; otherwise the previously set formatter, if any, will be deleted.

void IlEnvironment::setOption	(	char *	key,
		char *	value
	)

Set the value of an option under some key.

Parameters

key	The key used to store the value of the option.
value	The option value.

Note: Neither the key nor the value are copied.

IlBoolean IlEnvironment::setOptionValue	(	char *	key,
		char *	value
	)

Modify the value of an option under some key.

Parameters

key	The key used to store the value of the option.
value	The option value.

Returns: IlTrue if the assignment succeeded.

Note: The new value is not copied.

virtual IlBoolean IlEnvironment::setTimeZone ( UnicodeString tz )

virtual

Set the current time zone to the one defined by the given argument.

Parameters

tz	The time zone code as a UnicodeString

Returns: IlTrue if the time zone change went well.

Values for the argument must conform to those defined by ICU.

Note: If the UnicodeString argument does not name a known or recognized time zone, the time zone will be set to the GMT time zone.

Rogue Wave DBLink API Reference Guide

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation